---
title: RadioButtonList
description: >-
  The `RadioButtonList` component presents radio button options for single
  selection from a list of string values. Use it when merchants need to choose
  exactly one option from a defined set of choices.


  The component ensures single-selection behavior with clear visual indication
  of the selected option and disabled states for unavailable choices, making it
  suitable for settings, preferences, and any scenario requiring exclusive
  choice from multiple options.
api_version: 2024-07
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2024-07/ui-components/forms/radiobuttonlist
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2024-07/ui-components/forms/radiobuttonlist.md
---

# Radio​Button​List

The `RadioButtonList` component presents radio button options for single selection from a list of string values. Use it when merchants need to choose exactly one option from a defined set of choices.

The component ensures single-selection behavior with clear visual indication of the selected option and disabled states for unavailable choices, making it suitable for settings, preferences, and any scenario requiring exclusive choice from multiple options.

## Properties

Configure the following properties on the `RadioButtonList` component.

* items

  string\[]

  required

  An array of string values representing the radio button options available for selection.

* onItemSelected

  (item: string) => void

  required

  A callback function executed when a radio list item is selected, receiving the selected item string as a parameter. You must update the `initialSelectedItem` property in response to this callback to reflect the new selection.

* initialOffsetToShowSelectedItem

  boolean

  A boolean that determines whether the initially selected item renders at the top of the list, automatically scrolling to show the selected option.

* initialSelectedItem

  string

  The name of the currently selected item. You control the selection by setting this property and updating it when `onItemSelected` fires.

### Examples

* #### Select one option from a list

  ##### Description

  Present a list of mutually exclusive options for single selection. This example shows how to implement a RadioButtonList where merchants can choose exactly one option from multiple choices, ideal for settings, preferences, or filtering selections.

  ##### React

  ```tsx
  import React from 'react';
  import {
    reactExtension,
    RadioButtonList,
    Screen,
    ScrollView,
    Text,
  } from '@shopify/ui-extensions-react/point-of-sale';

  const SmartGridModal = () => {
    const [selected, setSelected] =
      React.useState('');

    return (
      <Screen
        name="RadioButtonList"
        title="RadioButtonList"
      >
        <ScrollView>
          <RadioButtonList
            items={['1', '2', '3']}
            onItemSelected={setSelected}
            initialSelectedItem={selected}
          />
          <Text>{selected}</Text>
        </ScrollView>
      </Screen>
    );
  };

  export default reactExtension(
    'pos.home.modal.render',
    () => {
      return <SmartGridModal />;
    },
  );
  ```

  ##### TS

  ```ts
  import {
    extension,
    RadioButtonList,
    Screen,
    ScrollView,
    Text,
  } from '@shopify/ui-extensions/point-of-sale';

  export default extension(
    'pos.home.modal.render',
    (root) => {
      const mainScreen = root.createComponent(
        Screen,
        {
          name: 'RadioButtonList',
          title: 'RadioButtonList',
        },
      );
      const scrollView =
        root.createComponent(ScrollView);

      const text = root.createComponent(Text);

      const radioButtonList = root.createComponent(
        RadioButtonList,
        {
          items: ['1', '2', '3'],
          onItemSelected: (selected) => {
            text.replaceChildren(selected);
            radioButtonList.updateProps({
              initialSelectedItem: selected,
            });
          },
        },
      );

      scrollView.append(radioButtonList);
      scrollView.append(text);

      mainScreen.append(scrollView);
      root.append(mainScreen);
    },
  );
  ```

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/pos-ui-extensions/2024-07/radio-button-list-default.png)

## Best practices

* **Manage selection state in your app:** Use `initialSelectedItem` and `onItemSelected` together to manage selection state. When a user selects an item, `onItemSelected` fires with the selected value—you must then update `initialSelectedItem` with this new value to reflect the selection in the UI.
* **Enable auto-scrolling for better UX:** Set `initialOffsetToShowSelectedItem` to true when you have long lists and want. This improves usability by eliminating the need for users to scroll to find their current selection.
* **Track selections in your app code:** Maintain the selected item value in your app state (for example, using React [`useState`](https://react.dev/reference/react/useState)). When `onItemSelected` fires, update your state with the new selection, which will then update the `initialSelectedItem` property to reflect the change.
* **Consider list length and scrolling:** For long option lists, use the `initialOffsetToShowSelectedItem` property to improve initial display. Design your interface to handle scrollable lists gracefully, especially on smaller POS device screens.

## Limitations

* `RadioButtonList` accepts only string arrays for options—complex option objects with additional metadata or custom rendering require alternative components or additional state management.
* The component is designed for single selection only—multiple selection scenarios require alternative approaches or custom implementation.
* `RadioButtonList` requires you to manage the selected value in your app must update `initialSelectedItem` in response to `onItemSelected` events to reflect the new selection in the UI.