Skip to content

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 ​

vue
<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 ​

PropTypeRequiredDescription
optionsStripePaymentMethodMessagingElementOptionsNoElement 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 ​

OptionTypeDescription
amountnumberRequired. 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)
paymentMethodTypesArray<'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
paymentMethodOrderArray<'affirm' | 'klarna' | 'afterpay_clearpay'>Fixed display order. By default Stripe orders them per customer
paymentMethodsArray<'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 ​

EventPayloadDescription
@readyStripePaymentMethodMessagingElementEmitted 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 ​

SlotSlot PropsDescription
#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)
vue
<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:

MemberTypeDescription
elementShallowRef<StripePaymentMethodMessagingElement | null>The Stripe element instance (null until created)
loadingRef<boolean>true until the element emits ready or loaderror
errorRef<string | null>Current creation or load error message
focus()() => voidFocus the element
blur()() => voidBlur the element
clear()() => voidClear 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:

vue
<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:

html
<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:

ts
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 ​

vue
<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 ​