OptionList

Deprecated

Product subscription app extensions won't be supported as of February 9, 2026. You should migrate existing product subscription app extensions to purchase options extensions.

Note: This component is not available in Product Subscription extensions.

Option lists let you create grouped items. This can include single selection or multiple selection of options. Option lists are styled differently than choice lists and should not be used within a form, but as a standalone menu.

import {extend, OptionList} from '@shopify/admin-ui-extensions';

extend('Playground', (root) => {

const options = [

{label: 'Red', value: 'red', disabled: false},

{label: 'Green', value: 'green', disabled: false},

{label: 'Blue', value: 'blue', disabled: false},

];

let selected = [];

const list = root.createComponent(OptionList, {

title: 'OptionList title',

options,

allowMultiple: true,

selected,

onChange: (newSelected) => {

console.log(`option selected: ${newSelected}`);

selected = newSelected;

});

root.appendChild(list);

root.mount();

});

import React, {useState} from 'react';

import {extend, render, OptionList} from '@shopify/admin-ui-extensions-react';

function App() {

const options = [

{label: 'Red', value: 'red', disabled: false},

{label: 'Green', value: 'green', disabled: false},

{label: 'Blue', value: 'blue', disabled: false},

];

const [selected, setSelected] = useState([]);

return (

<OptionList

title="OptionList title"

options={options}

selected={selected}

allowMultiple

onChange={(newSelected) => {

setSelected(newSelected);

console.log(`options selected: ${newSelected}`);

}}

);

}

extend(

'Playground',

render(() => <App />),

);

import {extend, OptionList} from '@shopify/admin-ui-extensions';

extend('Playground', (root) => {
  const options = [
    {label: 'Red', value: 'red', disabled: false},
    {label: 'Green', value: 'green', disabled: false},
    {label: 'Blue', value: 'blue', disabled: false},
  ];
  let selected = [];

  const list = root.createComponent(OptionList, {
    title: 'OptionList title',
    options,
    allowMultiple: true,
    selected,
    onChange: (newSelected) => {
      console.log(`option selected: ${newSelected}`);
      selected = newSelected;
    },
  });
  root.appendChild(list);

  root.mount();
});

import React, {useState} from 'react';
import {extend, render, OptionList} from '@shopify/admin-ui-extensions-react';

function App() {
  const options = [
    {label: 'Red', value: 'red', disabled: false},
    {label: 'Green', value: 'green', disabled: false},
    {label: 'Blue', value: 'blue', disabled: false},
  ];

  const [selected, setSelected] = useState([]);

  return (
    <OptionList
      title="OptionList title"
      options={options}
      selected={selected}
      allowMultiple
      onChange={(newSelected) => {
        setSelected(newSelected);
        console.log(`options selected: ${newSelected}`);
      }}
    />
  );
}

extend(
  'Playground',
  render(() => <App />),
);

Anchor to PropsProps

optional = ?

Name	Type	Description
title?	`string`	Title to display above the list
options?	`OptionDescriptor[]`	Array of options to be listed
selected	`string[]`	Array of selected options
allowMultiple?	`boolean`	Allow more than one option to be selected
onChange	`(selected: string[]) => void`	Callback when selection changes

Anchor to OptionDescriptorOptionDescriptor

Name	Type	Description
value	`string`	Value of the option
label	`string`	Display label for the option
disabled?	`boolean`	Whether the option is disabled or not

Anchor to GuidelinesGuidelines

✅ Do	🛑 Don't
Use OptionList to present either a single choice or multi choice list	Have only a single item

For more guidelines, refer to Polaris' Option List best practices.

Was this page helpful?