VueStripePaymentMethodMessagingElement
Displays buy-now-pay-later messaging (Affirm, Klarna, Afterpay / Clearpay) for an amount and currency. Wraps elements.create('paymentMethodMessaging'). Use it inside VueStripeElements. It is display-only: it collects no payment details. To add it to a product page, see Show buy-now-pay-later messaging.
Usage
<template>
<VueStripeProvider :publishable-key="publishableKey">
<VueStripeElements>
<VueStripePaymentMethodMessagingElement
:options="{
amount: 1099,
currency: 'USD',
paymentMethodTypes: ['klarna', 'afterpay_clearpay', 'affirm'],
countryCode: 'US'
}"
@ready="onReady"
/>
</VueStripeElements>
</VueStripeProvider>
</template>
<script setup lang="ts">
import '@vue-stripe/vue-stripe/style.css' // once, e.g. in main.ts
import {
VueStripeProvider,
VueStripeElements,
VueStripePaymentMethodMessagingElement
} from '@vue-stripe/vue-stripe'
const publishableKey = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY
const onReady = () => console.log('messaging ready')
</script>Props
| Prop | Type | Required | Description |
|---|---|---|---|
options | StripePaymentMethodMessagingElementOptions | No | Element options. Stripe requires amount and currency; see Options |
Updating options
Changes to options are applied to the mounted element with element.update(), and only when they really change: a re-render that passes a new but deep-equal object (e.g. an inline :options="{ ... }") does not call update(). Bind a computed amount to keep the message in step with the price.
Options
| Option | Type | Description |
|---|---|---|
amount | number | Required. Price in the smallest currency unit (cents for USD; see Amounts and currencies) |
currency | 'USD' | 'EUR' | 'GBP' | ... | Required. Upper-case ISO currency code: AUD, CAD, CHF, CZK, DKK, EUR, GBP, NOK, NZD, PLN, RON, SEK or USD |
countryCode | 'US' | 'GB' | 'DE' | ... | The customer's country. Decides which providers can be offered. Optional, but pass it: without it Stripe uses the visitor's location, and for a country it doesn't support the element fails to load (@loaderror) |
paymentMethodTypes | Array<'affirm' | 'klarna' | 'afterpay_clearpay'> | Optional. Limits the message to these providers. Without it, Stripe.js shows every provider that applies to the amount, currency and country |
paymentMethodOrder | Array<'affirm' | 'klarna' | 'afterpay_clearpay'> | Fixed display order. By default Stripe orders them per customer |
paymentMethods | Array<'affirm' | 'klarna' | 'afterpay_clearpay'> | Deprecated by Stripe; use paymentMethodTypes |
metaData | { messagingClientReferenceId: string | null } | Reference ID passed to Stripe |
@stripe/stripe-js 10 also declares logoColor, but Stripe.js Endive rejects it: elements.create() and every update() log "Unrecognized ... parameter: logoColor is not a recognized parameter" and the logos keep their default look. Leave it out.
paymentMethodTypes here is this element's own option (which messages to show). It is unrelated to the paymentMethodTypes prop that was removed from VueStripeElements in v6. Stripe's reference lists the supported currency and country combinations.
Events
| Event | Payload | Description |
|---|---|---|
@ready | StripePaymentMethodMessagingElement | Emitted when the element is mounted and ready |
@loaderror | { elementType: 'paymentMethodMessaging', error } | Emitted when the messaging fails to load, for example without countryCode for a visitor in a country Stripe doesn't support, or when the element can't be created. Ends the loading state and shows the #error slot |
The element is display-only, so it has no @change, @focus, @blur or @escape. Stripe.js 10's types declare only ready for this element, but Stripe.js emits loaderror at runtime and then destroys the element itself; the component listens for it, and unmounts cleanly afterwards. Stripe's load error carries no message, so error reads "Element failed to load". The exception is a wrong publishable key in a group with a clientSecret or mode: there error is Stripe's "Invalid API Key provided" message (VueStripeProvider).
Slots
| Slot | Slot Props | Description |
|---|---|---|
#loading | - | Rendered while the element is loading (default: "Loading payment method messaging...") |
#error | { error: string } | Rendered when the element has an error: a creation error or a load error (@loaderror) |
<VueStripePaymentMethodMessagingElement>
<template #loading>
<div class="skeleton-loader">Loading...</div>
</template>
<template #error="{ error }">
<p class="my-error">{{ error }}</p>
</template>
</VueStripePaymentMethodMessagingElement>Exposed Methods & Properties
Access these via a template ref:
| Member | Type | Description |
|---|---|---|
element | ShallowRef<StripePaymentMethodMessagingElement | null> | The Stripe element instance (null until created) |
loading | Ref<boolean> | true until the element emits ready or loaderror |
error | Ref<string | null> | Current creation or load error message |
focus() | () => void | Focus the element |
blur() | () => void | Blur the element |
clear() | () => void | Clear the element's value |
The component owns the element's lifecycle: it creates, mounts and destroys the element. Removing the component (for example with v-if) destroys the element, which takes the place of Stripe's element.unmount(); for a one-time listener use Vue's .once modifier (@ready.once) instead of element.once().
Refs are unwrapped on the template ref, so messagingRef.value.element is a StripePaymentMethodMessagingElement | null. Type the template ref with the component type and the element with the Stripe type:
<script setup lang="ts">
import { ref } from 'vue'
import { VueStripePaymentMethodMessagingElement } from '@vue-stripe/vue-stripe'
import type { StripePaymentMethodMessagingElement } from '@stripe/stripe-js'
const messagingRef = ref<InstanceType<typeof VueStripePaymentMethodMessagingElement> | null>(null)
const focus = () => messagingRef.value?.focus()
const clear = () => messagingRef.value?.clear()
const stripeElement = (): StripePaymentMethodMessagingElement | null => messagingRef.value?.element ?? null
</script>
<template>
<VueStripePaymentMethodMessagingElement
ref="messagingRef"
:options="{ amount: 1099, currency: 'USD', countryCode: 'US' }"
/>
<button type="button" @click="focus">Focus</button>
<button type="button" @click="clear">Clear</button>
<p v-if="stripeElement()">The Stripe element exists</p>
</template>Styling
The component renders this markup around Stripe's iframe:
<div class="vue-stripe-paymentMethodMessaging-element vue-stripe-element">
<!-- only when there is an error; an #error slot replaces the inner div -->
<div class="vue-stripe-paymentMethodMessaging-element-error vue-stripe-element-error">
<div class="vue-stripe-error-message">The error message</div>
</div>
<!-- Stripe mounts its iframe here; plus vue-stripe-paymentMethodMessaging-element-loading / vue-stripe-element-loading while loading -->
<div class="vue-stripe-paymentMethodMessaging-element-mount vue-stripe-element-mount"></div>
<!-- only while loading; a #loading slot replaces the inner div -->
<div class="vue-stripe-paymentMethodMessaging-element-loader vue-stripe-element-loader">
<div class="vue-stripe-loading-message">Loading payment method messaging...</div>
</div>
</div>The default styles for these classes ship in the package stylesheet. Import it once in your app:
import '@vue-stripe/vue-stripe/style.css'Target .vue-stripe-element* to style every element at once, or .vue-stripe-paymentMethodMessaging-element* for this one. Style elements covers the markup and the Appearance API.
TypeScript
<script setup lang="ts">
import { VueStripePaymentMethodMessagingElement } from '@vue-stripe/vue-stripe'
import type {
StripePaymentMethodMessagingElementOptions
} from '@stripe/stripe-js'
const options: StripePaymentMethodMessagingElementOptions = {
amount: 1099,
currency: 'USD',
countryCode: 'US'
}
</script>
<template>
<VueStripePaymentMethodMessagingElement :options="options" />
</template>See Also
- Show buy-now-pay-later messaging - Add the element to a product page and keep the amount in sync
- VueStripeElements - Parent that provides the Elements group
- VueStripePaymentElement - Collects the BNPL payment at checkout
- Live demo
