---
title: ToggleButtonGroup
description: >-
The toggle button group component lets customers make a single choice from a
set of options.
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/togglebuttongroup
md: >-
https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/togglebuttongroup.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.
# ToggleButtonGroup
The toggle button group component lets customers make a single choice from a set of options displayed as connected buttons. Use it for compact selection interfaces where all options should be visible at once.
For selections that need additional details or support multiple selections, use [ChoiceList](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/choicelist) instead.
### Support Targets (25)
### Supported targets
* CustomerAccount::KitchenSink
* [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
* **Quick selection**: Let customers pick an option with a single tap.
* **Time slots**: Present a small set of available times for scheduling.
* **Size selection**: Offer size options in a compact, visual layout.
* **Compact choices**: Save space compared to a full choice list with radio buttons.
***
## Properties
Configure the following properties on the ToggleButtonGroup component.
* **onChange**
**(value: T) => void**
**required**
A callback that is run whenever one of the buttons is pressed. This callback is called with a string or array of strings indicating the ids of buttons that should now be selected. When this component is [controlled](https://reactjs.org/docs/forms.html#controlled-components), you must store this value in state and reflect it back in the `value` prop.
* **value**
**T**
**required**
An id of the selected button.
* **disabled**
**boolean**
Whether the button group is disabled.
***
## Examples
### Choose from a set of options
Use toggle button group to present a small set of options that customers can select with a single tap. This example shows a basic toggle button group with selectable options.
## Choose from a set of options
## Choose from a set of options
##### React
```tsx
import {
reactExtension,
BlockStack,
InlineLayout,
Text,
ToggleButton,
ToggleButtonGroup,
View,
} from '@shopify/ui-extensions-react/customer-account';
export default reactExtension(
'customer-account.page.render',
() => ,
);
function Extension() {
return (
{
console.log(
`onChange event with value: ${value}`,
);
}}
>
None
100
points
200
points
300
points
);
}
```
##### JS
```js
import {
extension,
ToggleButtonGroup,
ToggleButton,
InlineLayout,
View,
BlockStack,
Text,
} 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(InlineLayout, {spacing: 'base'}, [
root.createComponent(
ToggleButton,
{id: 'none'},
root.createComponent(
View,
{
blockAlignment: 'center',
inlineAlignment: 'center',
minBlockSize: 'fill',
},
'None',
),
),
root.createComponent(
ToggleButton,
{id: 'points-100'},
root.createComponent(
BlockStack,
{inlineAlignment: 'center', spacing: 'none'},
[
root.createComponent(Text, undefined, '100'),
root.createComponent(Text, {appearance: 'subdued'}, 'points'),
],
),
),
root.createComponent(
ToggleButton,
{id: 'points-200'},
root.createComponent(
BlockStack,
{inlineAlignment: 'center', spacing: 'none'},
[
root.createComponent(Text, undefined, '200'),
root.createComponent(Text, {appearance: 'subdued'}, 'points'),
],
),
),
root.createComponent(
ToggleButton,
{id: 'points-300'},
root.createComponent(
BlockStack,
{inlineAlignment: 'center', spacing: 'none'},
[
root.createComponent(Text, undefined, '300'),
root.createComponent(Text, {appearance: 'subdued'}, 'points'),
],
),
),
]),
],
);
root.appendChild(toggleButtonGroup);
});
```
### Display a small set of time choices
The toggle button group component is ideal for a small set of options. It allows for easy scanning of available choices, and the component's large tap target makes it a good choice for an enhanced mobile experience. However, in a grid layout, having more than 6 toggle buttons can get overwhelming and take up too much vertical space. When there are more than 6 choices, consider using the [select](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/select) component instead.
## Display a small set of time choices
## Display a small set of time choices
##### React
```tsx
import {
reactExtension,
Grid,
ToggleButton,
ToggleButtonGroup,
View,
} from '@shopify/ui-extensions-react/checkout';
export default reactExtension(
'purchase.checkout.block.render',
() => ,
);
function Extension() {
return (
{
console.log(
`onChange event with value: ${value}`,
);
}}
>
9:00 AM
10:00 AM
11:00 AM
1:00 PM
2:00 PM
3:00 PM
);
}
```
##### JavaScript
```js
import {
extension,
Grid,
ToggleButtonGroup,
ToggleButton,
View,
} from '@shopify/ui-extensions/checkout';
export default extension(
'purchase.checkout.block.render',
(root) => {
const toggleButtonGroup =
root.createComponent(
ToggleButtonGroup,
{
value: 'time-9am',
onChange: (value) => {
console.log(
`onChange event with value: ${value}`,
);
},
},
[
root.createComponent(
Grid,
{
columns: ['auto', 'auto', 'auto'],
spacing: 'base',
},
[
root.createComponent(
ToggleButton,
{id: 'time-9am'},
root.createComponent(
View,
{inlineAlignment: 'center'},
'9:00 AM',
),
),
root.createComponent(
ToggleButton,
{id: 'time-10am'},
root.createComponent(
View,
{inlineAlignment: 'center'},
'10:00 AM',
),
),
root.createComponent(
ToggleButton,
{id: 'time-11am'},
root.createComponent(
View,
{inlineAlignment: 'center'},
'11:00 AM',
),
),
root.createComponent(
ToggleButton,
{id: 'time-1pm'},
root.createComponent(
View,
{inlineAlignment: 'center'},
'1:00 PM',
),
),
root.createComponent(
ToggleButton,
{id: 'time-2pm'},
root.createComponent(
View,
{inlineAlignment: 'center'},
'2:00 PM',
),
),
root.createComponent(
ToggleButton,
{id: 'time-3pm'},
root.createComponent(
View,
{inlineAlignment: 'center'},
'3:00 PM',
),
),
],
),
],
);
root.appendChild(toggleButtonGroup);
},
);
```
***
## Best practices
* **Limit the number of options**: Keep to six or fewer options to prevent visual clutter and maintain scannability.
* **Use for single selection**: Toggle button group supports single selection only. For multiple selections, use [ChoiceList](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/choicelist).
* **Keep labels concise**: Use short, scannable labels that fit within the buttons without wrapping.
***
## Limitations
* Only supports single selection. For multiple selections, use choice list.
***