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.
email, fullName, phone, and companyName accept a top-level required?: boolean.
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:
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
bank does not expose a top-level required knob. Both modes are implicitly required:
- Address-lookup 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
card does not accept required at any level. Every card field is always required. Suppress optional fields with fields.holderName.hidden or fields.postalCode.hidden instead.
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.
Container elements
checkout, submitButton, applePay, and googlePay do not accept required. Configure per-slot required on the contact and address slots inside checkout instead.
Error shape
Read errors from onChange.errors (live) or onError.fieldErrors (submit time). Both surfaces share the same FieldError shape.
See also
Last modified on July 17, 2026
