Custom elements reference

Complete reference for the four custom element types and the options they share.

Factories

overflow.text(options: CustomTextElementOptions): CustomTextElement
overflow.number(options: CustomNumberElementOptions): CustomNumberElement
overflow.select<TValue extends string>(
  options: CustomSelectElementOptions<TValue>,
): CustomSelectElement<TValue>
overflow.checkbox(options: CustomCheckboxElementOptions): CustomCheckboxElement

Shared options

Every custom element extends the same base:

type CustomElementBase<TElementType extends string, TValue> = {
  elementType: TElementType;
  name: string;                       // unique per Overflow instance
  label: string;                      // required
  placeholder?: string;
  defaultValue?: TValue;
  autocomplete?: AutoFill;            // HTML autofill token
  disabled?: boolean;
  readOnly?: boolean;
  id?: string;
  ariaLabel?: string;
  required?: boolean;
  validate?: (value: TValue) => string | null;
};

Key	Notes
`name`	Unique per `Overflow` instance. Used as the key inside `checkout.value.customElements[name]`, the `field` string on emitted `FieldError`, and the registry key for `checkout.getCustomElement(name)`. Duplicates log a warning and return a no-op handle.
`label`	Required. Renders as `<label>` and interpolates into the default `required` error message (`"<label> is required"`).
`placeholder`	Placeholder text on `text` and `number`. On `select`, when set, renders a selectable empty option at the top of the list. Not applicable to `checkbox`.
`defaultValue`	Seeds the DOM value on mount. No `onChange` fires from the seed. Read the seeded value via `element.value` before any interaction.
`autocomplete`	Forwarded to the input’s `autocomplete` DOM attribute. Accepts the full HTML autofill token grammar. Not applicable to `checkbox`.
`required`	`false` by default. When `true`, an empty input (or unchecked box) emits a `FieldError` with `code: 'required'`.
`validate`	Overrides all built-in checks when supplied. See Validate.
`disabled`	Renders the input disabled.
`readOnly`	Renders the input read-only. Not applicable to `checkbox`.
`id`	Custom `id` on the underlying input.
`ariaLabel`	Custom `aria-label`.

Value shapes

Element	`onChange.value`	`onSubmit.value`
`text`	`string \| null`	`string`
`number`	`number \| null`	`number`
`select`	`TValue \| null`	`TValue`
`checkbox`	`boolean`	`boolean`

text, number, and select emit null while empty or mid-typing an unparseable value. checkbox always has a state.

Events

Custom elements support the same six core events as built-in elements: onReady, onChange, onSubmit, onError, onFocus, onBlur, plus onEscapeKeyPressed. Wallet-only events (onClick, onExit) are not emitted.

Validation

Without validate, the only built-in check is the synchronous required empty check (unchecked-box on checkbox). Format checks are intentionally not provided because custom elements collect arbitrary merchant-defined data.
number adds built-in min and max range checks when validate is not supplied.
select accepts only values that match one of options[].value.
Providing validate skips every built-in check. The callback receives the current value (including null for empty inputs) and owns the entire validity contract. Return null for valid, or a non-empty string to surface a FieldError with code: 'custom'.

`FieldError`

interface FieldError {
  field: string;    // equals the element's configured `name`
  code: string;     // 'required', 'custom', 'min', 'max', 'invalid_format', ...
  message: string;  // already localized, safe to render
}

field always equals the element’s name. Bucket errors by field to place them next to the matching input.

Imperative value getters

Every custom element handle exposes read-only getters for the current snapshot. text, select, and checkbox expose .value. number is different: .value returns the raw display string as the shopper sees it (or ''), and .numericValue returns the parsed number | null. Use numericValue whenever you need to compute or forward the numeric value.

const tip = overflow.number({ name: 'tip', label: 'Tip', defaultValue: 5 });
tip.mount('#tip');

tip.value;        // '5' (display string)
tip.numericValue; // 5  (number | null)

text and select return null when empty.
number.value returns '' while empty; number.numericValue returns null.
checkbox always returns a boolean.

Inside Checkout

Custom elements can be configured under customElements on overflow.checkout(). Each slot appears on the aggregated envelope as:

value.customElements[name] = { elementType, value, complete };

Subscribe to a single slot’s events with checkout.getCustomElement(name). Inside Checkout, appearance is not allowed on custom slots. Style the whole Checkout as one cohesive unit; see Theming.

Duplicate names

Two elements with the same name on the same Overflow instance log a warning; the second one returns a no-op handle. Its mount, on, update, and submit calls are silently ignored.

Get started

Elements

Options

Events

Theming

Guides

Factories

Shared options

Value shapes

Events

Validation

`FieldError`

Imperative value getters

Inside Checkout

Duplicate names

See also

​Factories

​Shared options

​Value shapes

​Events

​Validation

​FieldError

​Imperative value getters

​Inside Checkout

​Duplicate names

​See also

Factories

Shared options

Value shapes

Events

Validation

`FieldError`

Imperative value getters

Inside Checkout

Duplicate names

See also