Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
loadStripe
✓ import { loadStripe, type Stripe } from '@stripe/stripe-js'
✗ const loadStripe = require('@stripe/stripe-js').loadStripe
This is the primary way to load Stripe.js programmatically. Remember to install `@stripe/stripe-js` alongside `vue-stripe-js`.
StripeElements
✓ import { StripeElements } from 'vue-stripe-js'
✗ const StripeElements = require('vue-stripe-js').StripeElements
Since v2.0.0, `vue-stripe-js` is ESM-only. CommonJS `require()` is no longer supported and will cause errors.
StripeElement
✓ import { StripeElement } from 'vue-stripe-js'
✗ import StripeElement from 'vue-stripe-js'
StripeElement is a named export. Attempting a default import will fail.
StripeElementsOptionsMode
✓ import type { StripeElementsOptionsMode } from '@stripe/stripe-js'
Type imports are crucial for TypeScript projects and should be imported from `@stripe/stripe-js`.
This quickstart demonstrates how to load Stripe.js, initialize StripeElements and StripeElement components for a Payment Element, and handle a form submission to confirm a payment intent in a Vue 3 TypeScript application.
<template>
<form
v-if="stripeLoaded"
@submit.prevent="handleSubmit"
>
<StripeElements
:stripe-key="publishableKey"
:instance-options="stripeOptions"
:elements-options="elementsOptions"
ref="elementsComponent"
>
<StripeElement
type="payment"
:options="paymentElementOptions"
ref="paymentComponent"
/>
</StripeElements>
<button type="submit">
Submit Payment
</button>
</form>
<div v-else>Loading Stripe...</div>
</template>
<script setup lang="ts">
import { onBeforeMount, ref } from "vue"
import { loadStripe } from "@stripe/stripe-js"
import { StripeElements, StripeElement } from "vue-stripe-js"
import type {
StripeElementsOptionsMode,
StripePaymentElementOptions,
} from "@stripe/stripe-js"
// Use your actual publishable key from Stripe Dashboard
const publishableKey = process.env.VITE_STRIPE_PUBLISHABLE_KEY ?? "pk_test_YOUR_KEY";
const stripeOptions = ref({
// Optional: https://stripe.com/docs/js/initializing#init_stripe_js-options
})
const elementsOptions = ref<StripeElementsOptionsMode>({
// Required: https://stripe.com/docs/js/elements_object/create#stripe_elements-options
mode: "payment",
amount: 1099, // Example: $10.99
currency: "usd",
appearance: {
theme: "flat",
},
})
const paymentElementOptions = ref<StripePaymentElementOptions>({
// Optional: https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options
})
const stripeLoaded = ref(false)
const clientSecret = ref("") // This should come from your backend
const elementsComponent = ref<typeof StripeElements | null>(null)
const paymentComponent = ref<typeof StripeElement | null>(null)
onBeforeMount(async () => {
try {
await loadStripe(publishableKey);
stripeLoaded.value = true;
// In a real application, you would call your backend here
// to create a PaymentIntent and fetch its client_secret.
// For this example, we'll simulate a client_secret.
clientSecret.value = "pi_FAKE_CLIENT_SECRET_TEST"; // Replace with actual client_secret
elementsOptions.value.clientSecret = clientSecret.value; // Assign clientSecret to elementsOptions
} catch (error) {
console.error("Failed to load Stripe.js or initialize elements:", error);
}
})
async function handleSubmit() {
if (!elementsComponent.value || !paymentComponent.value || !clientSecret.value) {
console.error("Stripe elements not ready or client secret missing.");
return;
}
const stripeInstance = elementsComponent.value.instance;
const elements = elementsComponent.value.elements;
if (!stripeInstance || !elements) {
console.error("Stripe or Elements instance not available.");
return;
}
console.log("Attempting to confirm payment...");
const { error } = await stripeInstance.confirmPayment({
elements,
confirmParams: {
return_url: window.location.origin + '/payment-complete',
},
});
if (error) {
console.error("Payment confirmation failed:", error.message);
// Display error to the user
} else {
console.log("Payment successful! Redirecting to return_url.");
// User will be redirected to return_url
}
}
</script>
Errors
Common errors & fixes
Failed to resolve import "@stripe/stripe-js" from "..." (e.g., in Vite build)
The `@stripe/stripe-js` package is a peer dependency of `vue-stripe-js` and was not installed.
fix`npm install @stripe/stripe-js` or `yarn add @stripe/stripe-js`
SyntaxError: Cannot use import statement outside a module
`vue-stripe-js` was imported using CommonJS `require()` syntax in an environment configured for ES Modules, or vice-versa, specifically after the v2.0.0 breaking change to ESM-only.
fixEnsure your project uses `import ... from '...'` statements for `vue-stripe-js` and configure your build system (e.g., `package.json` `"type": "module"`) to handle ES Modules correctly. Review the v2.0.0 upgrade guide.
Property "instance" was accessed during render but is not defined on instance.
A component ref (e.g., `elementsComponent.value?.instance`) is being accessed before the component is fully mounted or before Stripe.js has finished loading and initialized the instance.
fixEnsure that `stripeLoaded.value` is `true` and the component refs (`elementsComponent.value`, `paymentComponent.value`) are populated before attempting to access their properties or methods, typically within an `async`/`await` block after `loadStripe` completes or inside an event handler.
ReferenceError: Stripe is not defined
The Stripe.js library (from `js.stripe.com/v3/`) has not been loaded into the page's global scope before `loadStripe` is called or Stripe components attempt to initialize.
fixEnsure `loadStripe()` is called and awaited before mounting Stripe components, or include `<script src="https://js.stripe.com/v3/"></script>` in your `index.html` `<body>` and verify it loads successfully before Vue application initialization.
Audit
Dependencies
@stripe/stripe-jsrequiredRequired for loading Stripe.js and accessing its core functionalities. It is a peer dependency.