---
title: Form
description: >-
  The form component wraps form controls and enables implicit submission,
  allowing customers to submit from any input by pressing Enter.
api_version: 2026-07
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/web-components/forms/form
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/web-components/forms/form.md
api_name: customer-account-ui-extensions
---

# 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

* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/order-actions#order-index-announcement-)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/order-actions#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/profile-page-default#profile-announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

#### Use cases

* **Data collection**: Group related inputs like name, email, and message for a single submission.
* **Implicit submission**: Allow customers to press **Enter** from any field to submit the form without clicking a button.
* **Multi-field layouts**: Combine text fields, select menus, and text areas in a structured form with a submit button.
* **Field validation**: Display specific error messages on individual fields to guide customers toward valid input.

***

## Properties

Configure the following properties on the form component.

* **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.

### Events

The form component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events).

* **submit**

  **CallbackEventListener\<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.

```ts
(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.

```ts
TEvent & {
  currentTarget: HTMLElementTagNameMap[TTagName];
}
```

***

## Examples

### Submit 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.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/form-default-w0y2qghs.png)

## html

```html
<s-form>
  <s-text-field label="Email address"></s-text-field>
  <s-button variant="primary" type="submit">Submit</s-button>
</s-form>
```

### Show 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

```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>
```

### Combine 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

```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>
```

***

## Best 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.

***