Concepts

Every element in Payment Elements is built on the same four concepts. Once you understand them, every element in the SDK feels familiar.

The Overflow instance

You create one Overflow instance per page and keep it. The instance owns your publishable key, page-wide options (locale, theme, validation debounce), and every element you create. Do not construct a new Overflow(...) to change options at runtime — call overflow.update({ ... }) on the existing instance instead.

const overflow = new Overflow('live_pub_...', {
  locale: 'en-US',
  appearance: { variables: { colorPrimary: '#0a3783' } },
});

Publishable keys use one of two prefixes:

live_pub_… for production.
test_pub_… for staging or test.

Call overflow.destroy() when you are done to tear down the instance and every element it created.

Elements

An element is a self-contained payment UI component you mount into a host node on your page. You create one by calling a factory on your Overflow instance.

const card = overflow.card();
const bank = overflow.bank();
const applePay = overflow.applePay();
const checkout = overflow.checkout();

Every element exposes the same lifecycle:

const element = overflow.card(options);   // create
element.on('onChange', handler);            // subscribe to events
element.mount('#host');                     // render into your DOM
element.submit();                           // validate and emit onSubmit
element.unmount();                          // remove from DOM
element.destroy();                          // tear down and drop callbacks

Elements fall into a few categories:

Checkout: a composite element that renders a full payment form. Use it as your primary integration.
Payment methods: card, bank, applePay, googlePay. Mount standalone or nest inside Checkout.
Address elements: billingAddress, shippingAddress, with optional autocomplete.
Contact elements: email, fullName, phone, companyName.
Custom elements: text, number, select, checkbox for arbitrary metadata.
Submit button: a themed submit CTA (submitButton).

Options

Every element factory accepts an options object with a uniform shape:

Top-level keys control behavior. Examples: splitMode on fullName, defaultCountry on phone, mode on bank, paymentMethods on checkout.
fields carries per-input customization: label, placeholder, disabled, hidden, and so on.
BaseElementOptions are common to every element: disabled, readOnly, id, ariaLabel, locale, required, validate?. The cascade flows from the element to its fields; per-field overrides win.
Compound elements (Checkout) nest the standalone options shape under each per-method key. What you configure standalone works the same way inside Checkout.

overflow.card({
  disabled: false,
  fields: {
    cardNumber: { label: 'Card number' },
    holderName: { label: 'Name on card', hidden: false },
    postalCode: { hidden: true },
  },
});

See Options overview for the shared knobs.

Events

Every element emits six core events. Some elements emit more where it matters.

Event	Fires
`onReady`	Once, when the element is mounted and interactive.
`onChange`	On every value or completeness change, with `{ value, complete, errors }`.
`onSubmit`	After a successful `.submit()` call or wallet authorization, with the tokenized payload.
`onError`	When validation or a runtime action fails, with `{ elementType, code, message, fieldErrors?, cause? }`.
`onFocus` / `onBlur`	When focus enters or leaves the element.

Wallets add onClick (for pre-sheet gating) and onExit (when the shopper dismisses the sheet). Non-wallet, non-button elements add onEscapeKeyPressed.

overflow.card()
  .on('onReady', () => console.log('ready'))
  .on('onChange', ({ complete, errors }) => {
    payButton.disabled = !complete;
  })
  .on('onSubmit', ({ value }) => forwardToServer(value))
  .on('onError', ({ code, message }) => console.error(code, message));

Subscribing to an unsupported event is rejected at compile time. See Events overview.

Theming

Pass design tokens on the Overflow instance. Every mounted element inherits them.

new Overflow('live_pub_...', {
  appearance: {
    size: 'normal',               // 'compact' | 'normal' | 'large'
    shadowSize: 'md',              // optional elevation preset
    variables: {
      colorPrimary: '#0a3783',
      colorBorder: '#ededed',
      borderRadius: '6px',
    },
  },
});

Every optional token has a documented default. Element-scoped overrides layer on top for standalone elements; sub-elements inside Checkout share the parent’s theme. See Theming.

`complete` vs `value`

Two concepts govern when a form is ready to submit:

value is the current tokenized or typed data for an element. For payment methods it is null until submission produces a token; for input elements it is the current shopper input.
complete is a boolean that flips true when the element passes validation. For a card element, that means every required field is filled and format-valid; for an email element, that means the value matches the email schema.

Use complete from onChange to gate your Pay button. Read value from onSubmit to forward to your server.

card.on('onChange', ({ complete }) => {
  payButton.disabled = !complete;
});

card.on('onSubmit', ({ value }) => {
  fetch('/api/authorize', { method: 'POST', body: JSON.stringify(value) });
});

Standalone vs Checkout

You have two integration shapes:

Checkout renders shopper contact, addresses, and payment methods in one mount. One onSubmit returns the whole payload. Use this when you want a turnkey form.
Standalone mounts one element at a time. You gate your submit button on onChange.complete for each element, forward each .onSubmit payload yourself, and control the layout.

Start with Checkout unless you have a specific layout requirement it cannot meet. See Compose standalone elements for the standalone path.

Next steps

Quickstart

Mount your first element.

Checkout

Start with the composite element.

Elements

Browse every element.

Events

Full event reference.

Get started

Elements

Options

Events

Theming

Guides

The Overflow instance

Elements

Options

Events

Theming

`complete` vs `value`

Standalone vs Checkout

Next steps

Quickstart

Checkout

Elements

Events

​The Overflow instance

​Elements

​Options

​Events

​Theming

​complete vs value

​Standalone vs Checkout

​Next steps

Quickstart

Checkout

Elements

Events

The Overflow instance

Elements

Options

Events

Theming

`complete` vs `value`

Standalone vs Checkout

Next steps