Option list

The option list component lets you create a list of grouped items that merchants can pick from. This can include single selection or multiple selection of options. Option list usually appears in a popover, and sometimes in a modal or a sidebar. Option lists are styled differently than choice lists and should not be used within a form, but as a standalone menu.

Use for a group of similar selectable items when only one should be selectable at once.

import {Card, OptionList} from '@shopify/polaris';
import {useState} from 'react';

function OptionListExample() {
  const [selected, setSelected] = useState([]);

  return (
    <Card>
      <OptionList
        title="Inventory Location"
        onChange={setSelected}
        options={[
          {value: 'byward_market', label: 'Byward Market'},
          {value: 'centretown', label: 'Centretown'},
          {value: 'hintonburg', label: 'Hintonburg'},
          {value: 'westboro', label: 'Westboro'},
          {value: 'downtown', label: 'Downtown'},
        ]}
        selected={selected}
      />
    </Card>
  );
}

Use when you have a group of similar selectable items and more than one item can be selected at once.

import {Card, OptionList} from '@shopify/polaris';
import {useState} from 'react';

function MultipleOptionListExample() {
  const [selected, setSelected] = useState([]);

  return (
    <Card>
      <OptionList
        title="Manage sales channels availability"
        onChange={setSelected}
        options={[
          {value: 'online_store', label: 'Online Store'},
          {value: 'messenger', label: 'Messenger'},
          {value: 'facebook', label: 'Facebook'},
          {value: 'wholesale', label: 'Wholesale'},
          {value: 'buzzfeed', label: 'BuzzFeed'},
        ]}
        selected={selected}
        allowMultiple
      />
    </Card>
  );
}

Use sections when you have multiple groups of similar selectable items.

import {Card, OptionList} from '@shopify/polaris';
import {useState} from 'react';

function OptionListWithSectionsExample() {
  const [selected, setSelected] = useState([]);

  return (
    <Card>
      <OptionList
        onChange={setSelected}
        sections={[
          {
            options: [
              {value: 'type', label: 'Sale item type'},
              {value: 'kind', label: 'Sale kind'},
            ],
          },
          {
            title: 'Traffic',
            options: [
              {value: 'source', label: 'Traffic referrer source'},
              {value: 'host', label: 'Traffic referrer host'},
              {value: 'path', label: 'Traffic referrer path'},
            ],
          },
        ]}
        selected={selected}
        allowMultiple
      />
    </Card>
  );
}

Use when a set of selections won’t fit in the available screen space.

import {Button, Popover, OptionList} from '@shopify/polaris';
import {useState, useCallback} from 'react';

function OptionListInPopoverExample() {
  const [selected, setSelected] = useState([]);
  const [popoverActive, setPopoverActive] = useState(true);

  const togglePopoverActive = useCallback(
    () => setPopoverActive((popoverActive) => !popoverActive),
    [],
  );

  const activator = (
    <Button onClick={togglePopoverActive} disclosure>
      Options
    </Button>
  );

  return (
    <div style={{height: '275px'}}>
      <Popover
        active={popoverActive}
        activator={activator}
        onClose={togglePopoverActive}
      >
        <OptionList
          title="Inventory Location"
          onChange={setSelected}
          options={[
            {
              value: 'byward_market',
              label: 'Byward Market',
              active: true,
            },
            {value: 'centretown', label: 'Centretown'},
            {
              value: 'hintonburg',
              label: 'Hintonburg',
              active: true,
            },
            {value: 'westboro', label: 'Westboro'},
            {value: 'downtown', label: 'Downtown'},
          ]}
          selected={selected}
        />
      </Popover>
    </div>
  );
}

Props

Want to help make this feature better? Please share your feedback.

interface OptionListProps
id?string

A unique identifier for the option list.

title?string

List title.

options?[]

Collection of options to be listed.

role?string

Defines a specific role attribute for the list itself.

optionRole?string

Defines a specific role attribute for each option in the list.

sections?[]

Sections containing a header and related options.

selectedstring[]

The selected options.

allowMultiple?boolean

Allow more than one option to be selected.

verticalAlign?'top' | 'center' | 'bottom'

Vertically align child content to the center, top, or bottom.

onChange(selected: string[]) => void

Callback when selection is changed.

Best practices

The option list component should:

  • Be placed on its own inside a container. Usually the container behaves like a menu, as it does with popover. Don’t place other components within the same container.
  • Not be used when a select component will do.

Content guidelines

Option lists

Each item in an option list should be clear and descriptive.

Do

  • Traffic referrer source

Don’t

  • Source


Accessibility

Items in an option list are organized as list items (<li>) in an unordered list (<ul>) and are conveyed as a group of related elements to assistive technology users.

Controls in simple option lists are buttons, and controls in multiple option lists are checkboxes.

If you customize the option list, you can provide ARIA roles that fit the context. These roles must be valid according to the W3C ARIA specification to be conveyed correctly to screen reader users.

  • The role prop adds an ARIA role to the option list wrapper
  • The optionRole prop adds an ARIA role to the option list items