---
title: ToggleButton
description: >-
  The toggle button component creates individual selectable options within a
  toggle button group.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/togglebutton
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/togglebutton.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# ToggleButton

The toggle button component creates individual selectable options within a toggle button group. Each toggle button represents one choice that customers can select.

Toggle buttons support labels and values for form submission.

### Support Targets (25)

### Supported targets

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

#### Use cases

* **Option selection**: Present individual choices within a toggle button group.
* **Quick choices**: Let customers make fast, single-tap selections.
* **Compact controls**: Offer a space-efficient alternative to radio buttons.
* **Visual selection**: Highlight the active choice with a distinct pressed state.

***

## Properties

Configure the following properties on the ToggleButton component.

* **id**

  **string**

  **required**

  A unique identifier for the toggle button.

* **accessibilityLabel**

  **string**

  A label used for buyers using assistive technologies. When set, any `children` supplied to this component will not be announced to screen reader users.

* **disabled**

  **boolean**

  Disables the button, disallowing any interaction.

* **onPress**

  **() => void**

  Callback when button is pressed.

***

## Examples

### Create a toggle option

Use toggle button to define an individual selectable option inside a toggle button group. This example shows a single toggle button within its parent group.

## Create a toggle option

![A toggle button in a selectable state within a button group](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/togglebutton-default-CZovWOKw.png)

## Create a toggle option

##### React

```tsx
import {
  reactExtension,
  ToggleButton,
  ToggleButtonGroup,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <ToggleButtonGroup
      value="none"
      onChange={(value) => {
        console.log(
          `onChange event with value: ${value}`,
        );
      }}
    >
      <ToggleButton id="none">None</ToggleButton>
    </ToggleButtonGroup>
  );
}
```

##### JS

```js
import {
  extension,
  ToggleButtonGroup,
  ToggleButton,
} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const toggleButtonGroup = root.createComponent(
    ToggleButtonGroup,
    {
      value: 'none',
      onChange: (value) => {
        console.log(`onChange event with value: ${value}`);
      },
    },
    [root.createComponent(ToggleButton, {id: 'none'}, 'None')],
  );

  root.appendChild(toggleButtonGroup);
});
```

***

## Best practices

* **Keep labels short**: Use concise labels that fit within the button without wrapping.
* **Use consistent sizing**: Keep all toggle buttons in a group roughly the same width for visual balance.

***

## Limitations

* Must be used as a child of toggle button group.

***