---
title: ToggleButtonGroup
description: >-
  `ToggleButtonGroup` allows you to make a single choice out of the number of
  options provided. This is similar to the
  [ChoiceList](/docs/api/checkout-ui-extensions/components/forms/choicelist)
  component, but without controls such as checkbox or radio button.


  You can utilize our layout components to arrange `ToggleButtonGroup`.
api_version: 2025-07
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/components/forms/togglebuttongroup
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/components/forms/togglebuttongroup.md
---

# Toggle​Button​Group

`ToggleButtonGroup` allows you to make a single choice out of the number of options provided. This is similar to the [ChoiceList](https://shopify.dev/docs/api/checkout-ui-extensions/components/forms/choicelist) component, but without controls such as checkbox or radio button.

You can utilize our layout components to arrange `ToggleButtonGroup`.

## ToggleButtonGroupProps

* 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

* #### Basic ToggleButtonGroup

  ##### React

  ```tsx
  import {
    reactExtension,
    BlockStack,
    InlineLayout,
    Text,
    ToggleButton,
    ToggleButtonGroup,
    View,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    return (
      <ToggleButtonGroup
        value="none"
        onChange={(value) => {
          console.log(
            `onChange event with value: ${value}`,
          );
        }}
      >
        <InlineLayout spacing="base">
          <ToggleButton id="none">
            <View
              blockAlignment="center"
              inlineAlignment="center"
              minBlockSize="fill"
            >
              None
            </View>
          </ToggleButton>
          <ToggleButton id="points-100">
            <BlockStack
              inlineAlignment="center"
              spacing="none"
            >
              <Text>100</Text>
              <Text appearance="subdued">
                points
              </Text>
            </BlockStack>
          </ToggleButton>
          <ToggleButton id="points-200">
            <BlockStack
              inlineAlignment="center"
              spacing="none"
            >
              <Text>200</Text>
              <Text appearance="subdued">
                points
              </Text>
            </BlockStack>
          </ToggleButton>
          <ToggleButton id="points-300">
            <BlockStack
              inlineAlignment="center"
              spacing="none"
            >
              <Text>300</Text>
              <Text appearance="subdued">
                points
              </Text>
            </BlockStack>
          </ToggleButton>
        </InlineLayout>
      </ToggleButtonGroup>
    );
  }
  ```

  ##### JS

  ```js
  import {
    extension,
    ToggleButtonGroup,
    ToggleButton,
    InlineLayout,
    View,
    BlockStack,
    Text,
  } from '@shopify/ui-extensions/checkout';

  export default extension('purchase.checkout.block.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);
  });
  ```

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/togglebuttongroup-default.png)

## Best Practices

ToggleButtonGroup is a component designed for streamlined single-choice selection, without any additional details associated with the selection. If you need to allow multiple selections or present associated details, it is recommended to use [ChoiceList](https://shopify.dev/docs/api/checkout-ui-extensions/components/forms/choicelist) instead.

### Label and order

Use descriptive and concise labels for each Toggle button, and maintain consistency in the terminology used across options. Arrange the Toggle buttons in a logical order that makes sense to users. Consider factors such as alphabetical order, chronological order, or order of importance, depending on the context.

### Number of Toggle buttons

Avoid overwhelming users with too many Toggle buttons. Ideally, limit the number of choices to a manageable amount, typically between 2 and 7, to prevent decision fatigue and maintain clarity.

## Examples

Displaying a small set of time choices

The ToggleButtonGroup component is ideal for a small set of options. It allows for easy scanning of available choices. Also the component’s big tap target makes it a good choice for enhanced mobile experience. However, in a grid layout, having more than 6 ToggleButtons 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/checkout-ui-extensions/components/forms/select) component instead.

### Examples

* #### Displaying a small set of time choices

  ##### Description

  The ToggleButtonGroup component is ideal for a small set of options. It allows for easy scanning of available choices. Also the component’s big tap target makes it a good choice for enhanced mobile experience. However, in a grid layout, having more than 6 ToggleButtons can get overwhelming and take up too much vertical space. When there are more than 6 choices, consider using the \[Select]\(/docs/api/checkout-ui-extensions/components/forms/select) component instead.

  ##### React

  ```jsx
  import {
    reactExtension,
    Grid,
    ToggleButton,
    ToggleButtonGroup,
    View,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    return (
      <ToggleButtonGroup
        value="time-9am"
        onChange={(value) => {
          console.log(
            `onChange event with value: ${value}`,
          );
        }}
      >
        <Grid
          columns={['auto', 'auto', 'auto']}
          spacing="base"
        >
          <ToggleButton id="time-9am">
            <View inlineAlignment="center">
              9:00 AM
            </View>
          </ToggleButton>
          <ToggleButton id="time-10am">
            <View inlineAlignment="center">
              10:00 AM
            </View>
          </ToggleButton>
          <ToggleButton id="time-11am">
            <View inlineAlignment="center">
              11:00 AM
            </View>
          </ToggleButton>
          <ToggleButton id="time-1pm">
            <View inlineAlignment="center">
              1:00 PM
            </View>
          </ToggleButton>
          <ToggleButton id="time-2pm">
            <View inlineAlignment="center">
              2:00 PM
            </View>
          </ToggleButton>
          <ToggleButton id="time-3pm">
            <View inlineAlignment="center">
              3:00 PM
            </View>
          </ToggleButton>
        </Grid>
      </ToggleButtonGroup>
    );
  }
  ```

  ##### 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);
    },
  );
  ```

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/togglebuttongroup-time-picking.png)

## Related

[![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/components/forms/togglebutton)

[ComponentToggleButton](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/components/forms/togglebutton)