Choose a version:

RadioButtonList

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.

Support

Targets (6)

Supported targets

Use cases

Single selection: Create options where users must select exactly one choice from alternatives.
Filtering controls: Implement filtering where users choose a single category or status.
Payment options: Provide option selection for payment methods or shipping options.
Preference selection: Enable preference selection for display modes or sort orders.

Anchor to examplesExamples

Anchor to example-select-one-option-from-a-listSelect one option from a list

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.

Select one option from a list

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"

>

<RadioButtonList

items={['1', '2', '3']}

onItemSelected={setSelected}

initialSelectedItem={selected}

/>

<Text>{selected}</Text>

</ScrollView>

</Screen>

);

};

export default reactExtension(

'pos.home.modal.render',

() => {

return <SmartGridModal />;

},

);

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

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

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

Anchor to propertiesProperties

Configure the following properties on the RadioButtonList component.

Anchor to items items string[] required: An array of string values representing the radio button options available for selection.
Anchor to onItemSelected 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.
Anchor to initialOffsetToShowSelectedItem 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.
Anchor to initialSelectedItem initialSelectedItem string: The name of the currently selected item. You control the selection by setting this property and updating it when onItemSelected fires.

Anchor to best-practicesBest 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). 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.

Anchor to limitationsLimitations

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.

Was this page helpful?