Upcoming — generated from the latest merged element source; documents unreleased development. Use the channel picker at the top of the sidebar for the docs of a published release.
Payments group: mint it with payments.create('cardFields', { … }) (vanilla) or render <CardFields> inside <Payments> (React — mount mints, unmount destroys), then mount its elements off the minted handle. destroy() tears it down and frees its place for the alternatives — a later create('cardFields') boots fresh.
Exclusive — when using
CardFields, you can’t mount PaymentElement or CardElement in the same Payments handle: these are alternatives — mount one at a time; destroy it to mount another.Preview
A live, interactive demo of this sub-controller’s default arrangement with sample data:Usage
Options
Pass these topayments.create('cardFields', { … }) — or as props on <CardFields> in React. Parent-injected props never appear here.
"compact" | "stacked"
How the composed card faces draw their cell chrome: ‘stacked’ (default) shapes the number as the top cell with expiration and security code as the bottom row; ‘compact’ shapes all three as segments of one single-row container. The fused card element forwards its own
layout; on the exploded face you own where each field mounts and every field draws fully independent chrome — all corners rounded, full border. Defaults to "stacked".string
Advanced: a Basis Theory publishable key to use instead of reading the matrix card entry. The composing card faces supply it from the matrix they already hold; omitted, the unit fetches its own.
Events
Pass a callback in the create options / React props.onChange
Field completeness changed — complete: true means all three fields are filled so the confirm can run; drive your pay button off it. brand is the detected card network.
Signature: ((payload: { complete: boolean; brand: string; }) => void)
onLoadingChange
Fired when the grouped loading state changes — true while any mounted element is still loading.
Signature: ((loading: boolean) => void)
Methods
Call these on the minted sub handle — the return ofpayments.create('cardFields', { … }).
tokenize
Tokenize the three mounted fields into a card credential WITHOUT minting a confirmation token (also emitted to the declaring controller as tokenized) — the advanced seam; confirming a payment wants payments.createConfirmationToken. Validation failures land on the failing field and throw a legible error.
Signature: (input: { accountId?: string | undefined; apiBaseUrl?: string | undefined; }) => Promise<{ token: string; }>
collect
The exploded face’s collection — payments.createConfirmationToken (the confirm cascade) is the verb to call; this surface action is where its cardFields branch lands: tokenizes the fields and returns the collected bag the controller mints from.
Signature: (input: { billingDetails?: { email?: string | undefined; name?: string | undefined; address?: { country?: string | undefined; line1?: string | undefined; city?: string | undefined; postal_code?: string | undefined; } | undefined; } | undefined; }) => Promise<{ paymentMethod: { type: string; category: string; card: { token: string; }; }; billingDetails: { email: string; name?: string | undefined; address?: { country?: string | undefined; line1?: string | undefined; city?: string | undefined; postal_code?: string | undefined; } | undefined; }; }>
update
Live-update the sub-controller’s consumer props and on<Event> callbacks.
Signature: (options: Partial<CardFieldsSubOptions>) => void
destroy
Tear the sub-controller down: its mounted elements are destroyed, its runtime state is discarded, and its exclusive slot is freed — a later create("cardFields") boots fresh.
Signature: () => void
Elements
The elements this sub-controller mounts — each has its own page:CardFieldsCardNumberElement
The PCI card number field — a Basis Theory hosted input under frosted chrome. A child of the card unit; the card number never touches this page.
CardFieldsCardExpiryElement
The PCI card expiration field — a Basis Theory hosted input under frosted chrome. A child of the card unit.
CardFieldsCardCvcElement
The PCI security code field — a Basis Theory hosted input under frosted chrome. A child of the card unit.