Choose a version:

Form

The form component wraps form controls and enables implicit submission, allowing customers to submit from any input by pressing Enter. Use form to group related input fields and handle form submission through JavaScript event handlers.

Unlike HTML forms, form doesn't automatically submit data using HTTP—you must register a submit event to process form data programmatically.

Form doesn't automatically submit data over HTTP. Register a submit event handler to process form data in your extension.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the form component.

Anchor to id id string: A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.

Anchor to EventsEvents

The form component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to submit submit <typeof tagName>: A callback fired when the form is submitted.

CallbackEventListener

A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.

(EventListener & {
      (event: CallbackEvent<TTagName, TEvent>): void;
    }) | null

CallbackEvent

An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.

TEvent & {
  currentTarget: HTMLElementTagNameMap[TTagName];
}

Anchor to ExamplesExamples

Anchor to Submit a basic formSubmit a basic form

Group input fields that submit together when a customer presses Enter or clicks a submit button. This example shows a basic form with a text field and submit button.

Submit a basic form

A form container with input fields and a submit button for collecting user data.

html

<s-form>

<s-text-field label="Email address"></s-text-field>

<s-button variant="primary" type="submit">Submit</s-button>

</s-form>

Anchor to Show field validation errorsShow field validation errors

Display specific error messages on individual fields to guide customers toward valid input. This example shows a form with required fields and inline validation errors.

html

<s-form>

<s-stack direction="block" gap="base">

<s-text-field label="Full name" name="name" required error="Name is required"></s-text-field>

<s-email-field label="Email" name="email" required error="Enter a valid email address"></s-email-field>

<s-button variant="primary" type="submit">Submit</s-button>

</s-stack>

</s-form>

Anchor to Combine different field typesCombine different field types

Mix text inputs with selects and checkboxes to capture different kinds of customer input. This example combines a text field, a select dropdown, and a checkbox.

html

<s-form>

<s-stack direction="block" gap="base">

<s-text-field label="Order reference" name="reference" required></s-text-field>

<s-select label="Reason for contact" name="reason">

<s-option value="return">Return request</s-option>

<s-option value="exchange">Exchange</s-option>

<s-option value="other">Other</s-option>

</s-select>

<s-checkbox label="I've read the return policy" name="policy"></s-checkbox>

<s-button variant="primary" type="submit">Submit request</s-button>

</s-stack>

</s-form>

Anchor to Best practicesBest practices

Place one submit button per form: Include a single submit button at the end of the form to keep the submission flow clear.
Register a submit handler: Form doesn't submit data over HTTP. Register a submit event listener to process form data programmatically.
Group related fields: Wrap only related inputs in a single form. Use separate forms for independent data collection tasks.

Was this page helpful?