required

required marks an element (or an individual atom on a multi-field element) as mandatory. Empty inputs surface a FieldError with code: 'required'. Defaults to false. When false, an empty input is treated as a valid “not provided” value: onChange emits value: null with no errors and submit() accepts the empty submission.

Single-input elements

email, fullName, phone, and companyName accept a top-level required?: boolean.

overflow.email({ required: true });
overflow.phone({ required: true });

When true, the element emits a FieldError with code: 'required' whenever its input is empty: at submit time, on blur, and from onChange as soon as the value becomes empty again. Backspacing to empty re-emits the required error immediately.

Split-mode `fullName`

required: true cascades to both halves. Each empty half emits its own FieldError with field: 'firstName' or field: 'lastName'.

Address elements

billingAddress and shippingAddress accept either a boolean or a per-atom record:

type MultiFieldRequired<TFieldKey extends string> =
  | boolean
  | Partial<Record<TFieldKey, boolean>>;

type AddressFieldKey =
  | 'line1' | 'line2' | 'city' | 'state' | 'zip' | 'country';

Shape	Behavior
unset	The element is fully optional. Empty atoms emit no `required` errors.
`required: true`	Cascades to `line1`, `city`, `state`, `zip`, and `country`. `line2` stays optional by convention.
`required: { line1: true, line2: true, ... }`	Per-atom override. Atoms not listed (or set to `false`) are optional. Hidden atoms are excluded from the cascade entirely.

overflow.billingAddress({
  required: { line1: true, city: true, state: true, zip: true, country: true, line2: false },
});

The optional fields.fullName slot on an address element owns its own required knob (configured inside fields.fullName.required). It is not addressable through the address-level record.

Bank element

Both bank modes are implicitly required:

Plaid mode: the shopper must complete linking before submit succeeds. An unlinked submit surfaces a single FieldError with field: 'bank' and code: 'required' and the message "Please link your bank to continue.".
Manual mode: every visible atom (accountType, routingNumber, accountNumber, confirmAccountNumber) is implicitly required and collects a required FieldError when empty. accountType only trips the required-empty branch when fields.accountType.placeholder is configured.

Card element

Every visible card field is required. Suppress optional atoms with fields.holderName.hidden, fields.postalCode.hidden, or fields.cardSecurityCode.hidden.

Custom elements

text, number, and select accept a top-level required?: boolean. An empty input (or the placeholder slot on select) emits a FieldError with code: 'required'. checkbox interprets required: true as “must be checked”, matching the native HTML <input type="checkbox" required> semantic.

Wallets, submit button, and Checkout

Wallets (applePay, googlePay) run their own submission and submitButton has no value. Inside checkout, configure required on individual slots (contact.email.required, billingAddress.required, and so on).

Error shape

{
  field: 'email',       // element's field key
  code: 'required',
  message: 'Email is required',  // interpolated from label
}

Read errors from onChange.errors (live) or onError.fieldErrors (submit time). Both surfaces share the same FieldError shape.

Get started

Elements

Options

Events

Theming

Guides

Single-input elements

Split-mode `fullName`

Address elements

Bank element

Card element

Custom elements

Wallets, submit button, and Checkout

Error shape

See also

​Single-input elements

​Split-mode fullName

​Address elements

​Bank element

​Card element

​Custom elements

​Wallets, submit button, and Checkout

​Error shape

​See also

Single-input elements

Split-mode `fullName`

Address elements

Bank element

Card element

Custom elements

Wallets, submit button, and Checkout

Error shape

See also