---
title: Checkbox
description: >-
  The checkbox component provides a clear way for users to make selections, such
  as agreeing to terms, enabling settings, or choosing multiple items from a
  list. Use checkbox to create binary on/off controls or multi-select interfaces
  where users can select any combination of options.
api_version: 2026-04
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/checkbox
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/checkbox.md
---

# Checkbox

The checkbox component provides a clear way for users to make selections, such as agreeing to terms, enabling settings, or choosing multiple items from a list. Use checkbox to create binary on/off controls or multi-select interfaces where users can select any combination of options.

Checkboxes support labels and error states. For settings that take effect immediately, use [switch](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/switch) instead.

### Support Targets (24)

### Supported targets

* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-announcement-)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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-04/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-04/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-04/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-04/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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-04/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-04/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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-04/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-04/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-04/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

#### Use cases

* **Marketing opt-in**: Let customers subscribe to email or SMS marketing with a pre-checked or unchecked default.
* **Terms acceptance**: Require agreement to terms of service or privacy policies before submission.
* **Add-on selection**: Allow customers to select optional extras like gift wrapping or extended warranties.

***

## Properties

Configure the following properties on the checkbox component.

* **accessibilityLabel**

  **string**

  A label used for users using assistive technologies like screen readers. When set, any children or `label` supplied will not be announced. This can also be used to display a control without a visual label, while still providing context to users using screen readers.

* **checked**

  **boolean**

  **Default: false**

  Whether the control is currently checked.

* **command**

  **'--auto' | '--show' | '--hide' | '--toggle'**

  **Default: '--auto'**

  Sets the action the `commandFor` target should take when this component is activated. Available options:

  * `'--auto'`: Performs the default action appropriate for the target component.
  * `'--show'`: Displays the target component if it's currently hidden.
  * `'--hide'`: Conceals the target component from view.
  * `'--toggle'`: Alternates the target component between visible and hidden states.
  * `'--copy'`: Copies the target clipboard item.

  The supported actions vary by target component type. Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).

* **commandFor**

  **string**

  The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).

  When both `commandFor` and `href` are set, `commandFor` takes precedence. The command runs and the link doesn't navigate.

* **defaultChecked**

  **boolean**

  **Default: false**

  Whether the control is checked by default.

* **disabled**

  **boolean**

  **Default: false**

  Whether the control is disabled, preventing any user interaction.

* **error**

  **string**

  An error message displayed below the field to indicate validation problems. When set, the field is styled with error indicators and the message is announced to screen readers.

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

* **label**

  **string**

  The visual content to use as the control label. Use a string to provide a simple text label displayed to the user.

  If a `label` slot is also provided, the slot content takes precedence. [Learn more about slots](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/checkbox#slots-propertydetail-label).

* **name**

  **string**

  The name attribute for the control, used to identify its value when the form is submitted. Must be unique within the nearest containing form.

* **required**

  **boolean**

  **Default: false**

  Whether the field needs a value. This requirement adds semantic value to the field, but it will not cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the `error` property.

  Adds semantic meaning for accessibility. Doesn't trigger automatic validation or display an error. Implement validation logic yourself and use the `error` prop to show results.

* **value**

  **string**

  The value used in form data when the control is checked.

### Events

The checkbox 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).

* **change**

  **CallbackEventListener\<typeof tagName>**

  A callback fired when the checkbox value changes.

  Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).

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

### Opt in to email marketing

Pre-fill a marketing opt-in checkbox with a checked default state. This example shows a checkbox with `checked` and a descriptive label.

## Opt in to email marketing

![A checkbox input with a label that can be checked or unchecked.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/checkbox-default-Co-Lw8O4.png)

## html

```html
<s-checkbox checked label="Email me with news and offers"></s-checkbox>
```

### Require agreement before continuing

Enforce agreement to terms of service before continuing. This example uses a checkbox with `required` and an `error` message when the customer hasn't accepted.

## html

```html
<s-checkbox
  label="I agree to the terms of service"
  required
  error="You must accept the terms to continue"
></s-checkbox>
```

### Disable an unavailable option

Disable a checkbox when the corresponding option isn't currently available. This example displays a checkbox with the `disabled` attribute for a newsletter subscription.

## html

```html
<s-checkbox label="Subscribe to newsletter" disabled></s-checkbox>
```

***

## Best practices

* **Write descriptive labels**: Use clear, specific text that explains what the customer is agreeing to or selecting.
* **Pre-check thoughtfully**: Only use `checked` for options that benefit the customer. Don't pre-check options that add cost.
* **Show validation errors inline**: Use the `error` property to display messages directly below the checkbox for required fields.
* **Pair with forms**: Use checkboxes inside a [form](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/form) when selections need to be submitted together with other input.

***