Custom elements section

The Custom elements section holds merchant-defined fields you configure per integration. Each slot is one mounted child managed by Checkout, keyed by a name you choose.

Enable the section

Pass customElements as an object of named slots. Each slot picks one of the Custom element types.

overflow.checkout({
  paymentMethods: ['card'],
  customElements: {
    giftMessage: {
      elementType: 'text',
      label: 'Gift message (optional)',
      required: false,
    },
    coverFee: {
      elementType: 'checkbox',
      label: 'Cover the processing fee',
      defaultValue: false,
    },
    quantity: {
      elementType: 'number',
      label: 'Quantity',
      min: 1,
      max: 10,
      required: true,
    },
  },
});

Supported elementType values:

'text': single-line text input. See Text.
'number': numeric input with optional min / max / step. See Number.
'select': dropdown with typed options. See Select.
'checkbox': boolean checkbox. See Checkbox.

Section position

The section renders after Payment methods by default. Move it with order:

overflow.checkout({
  paymentMethods: ['card'],
  customElements: { note: { elementType: 'text', label: 'Order note' } },
  order: ['contact', 'customElements', 'paymentMethods'],
});

Programmatic access

Reach into a slot with checkout.getCustomElement(name):

const gift = checkout.getCustomElement('giftMessage');
gift?.on('onChange', ({ value }) => console.log('gift message:', value));

Returns null if the slot is not configured.

Submitted value

Custom values are folded into the Checkout payload, keyed by slot name:

checkout.on('onSubmit', ({ value }) => {
  // value.customElements: { giftMessage: string | null, coverFee: boolean, quantity: number | null }
});

Each entry is the current typed value from the corresponding element.

Get started

Elements

Options

Events

Theming

Guides

Enable the section

Section position

Programmatic access

Submitted value

See also

​Enable the section

​Section position

​Programmatic access

​Submitted value

​See also

Enable the section

Section position

Programmatic access

Submitted value

See also