Components and appearance

Choose the fields your checkout needs, then apply an appearance at the provider or individual component level.

Component map

The framework components are thin wrappers around the corresponding custom elements.

Compose payment surfaces

Mount ExpressCheckoutElement before contact and shipping fields to offer Apple Pay without waiting for the ordinary form. It renders only when Apple Pay is enabled for the session and available in the browser. Set showSeparator when ordinary checkout fields follow it.

For card and bank payments, mount exactly one ordinary payment surface under a provider:

• PaymentElement shows the supported card and us_bank_account methods in the checkout session. Its paymentMethodLayout is "tabs" by default and can be "radio".
• CardElement selects card and only renders card fields. The session must enable card.
• USBankAccountElement selects a US bank account and only renders bank fields. The session must enable us_bank_account.

Mounting a second ordinary payment surface, including a duplicate of the first, is a terminal configuration_error. ExpressCheckoutElement is separate and may be mounted alongside that ordinary surface.

Collect shopper details

ContactElement collects and saves the shopper’s email. AddressElement accepts:

A billing address is attached to the payment method. A shipping address is saved to the checkout session. When both address scopes are present, the billing form can offer to reuse the shipping address. Contact and address values autosave while the shopper fills out the form and are flushed before payment submission.

Only mount fields your checkout needs. A mounted contact or address component registers its fields as required; an unmounted component does not block submission.

Configure appearance

Set appearance on the provider to theme the whole tree. Set it on a payment, contact, or address component to override that subtree. Component variables merge by key with provider variables, and component-level labelStyle wins.

<BiasProvider
    clientSecret={clientSecret}
    appearance={{
        labelStyle: "floating",
        variables: {
            colorPrimary: "#4f46e5",
            colorForeground: "#18181b",
            colorBorder: "#d4d4d8",
            borderRadius: "10px",
            fontFamily: "Inter, system-ui, sans-serif",
            fontSize: "16px",
            gap: "14px",
        },
    }}
>
    <ExpressCheckoutElement showSeparator />
    <ContactElement />
    <PaymentElement appearance={{ variables: { colorInput: "#fafafa" } }} />
    <SubmitButton />
</BiasProvider>

For web components, assign structured values as DOM properties:

const provider = document.querySelector("bias-provider");
provider.appearance = {
    labelStyle: "floating",
    variables: { colorPrimary: "#4f46e5", borderRadius: "10px" },
};

HTML attributes only carry strings, so an appearance attribute cannot represent this object.

Appearance options

labelStyle accepts "static", "floating", or "placeholder". The default is "static".

variables accepts optional CSS values for:

Replace the appearance object when updating it. Removing a variable from the new object removes the package-applied override and restores inheritance or the default.

SubmitButton has no component-level appearance prop. It inherits the provider theme and accepts only disabled and label.