Skip to content
Svelte Polaris Svelte Polaris

OptionList

OptionList displays a list of options that users can select from. It’s commonly used in dropdowns, selection interfaces, and anywhere you need to present choices to users in a clean, organized way.

Examples

Section titled “Examples”

Basic option list

Section titled “Basic option list”

Use OptionList to display a simple list of selectable options.

<script>
  import { OptionList, Card, Text, BlockStack } from 'svelte-polaris';


  let selectedOptions = ['today'];


  const options = [
    { value: 'today', label: 'Today' },
    { value: 'yesterday', label: 'Yesterday' },
    { value: 'last_week', label: 'Last week' },
    { value: 'last_month', label: 'Last month' },
    { value: 'last_year', label: 'Last year' }
  ];


  function handleChange(selected) {
    selectedOptions = selected;
  }
</script>


<Card>
  <BlockStack gap="300">
    <Text variant="headingMd">Date Range</Text>
    <OptionList
      title="Select time period"
      options={options}
      selected={selectedOptions}
      onChange={handleChange}
    />
    <Text>Selected: {selectedOptions.join(', ')}</Text>
  </BlockStack>
</Card>

Multiple selection

Section titled “Multiple selection”

Allow users to select multiple options from the list.

<script>
  import { OptionList, Card, Text, BlockStack, InlineStack, Tag } from 'svelte-polaris';


  let selectedOptions = ['email', 'sms'];


  const options = [
    { value: 'email', label: 'Email notifications' },
    { value: 'sms', label: 'SMS notifications' },
    { value: 'push', label: 'Push notifications' },
    { value: 'in_app', label: 'In-app notifications' },
    { value: 'browser', label: 'Browser notifications' }
  ];


  function handleChange(selected) {
    selectedOptions = selected;
  }


  function removeOption(value) {
    selectedOptions = selectedOptions.filter(option => option !== value);
  }
</script>


<Card>
  <BlockStack gap="300">
    <Text variant="headingMd">Notification Preferences</Text>


    {#if selectedOptions.length > 0}
      <div>
        <Text variant="bodyMd">Selected notifications:</Text>
        <InlineStack gap="100">
          {#each selectedOptions as option}
            <Tag onRemove={() => removeOption(option)}>
              {options.find(opt => opt.value === option)?.label}
            </Tag>
          {/each}
        </InlineStack>
      </div>
    {/if}


    <OptionList
      title="Choose notification methods"
      options={options}
      selected={selectedOptions}
      onChange={handleChange}
      allowMultiple
    />
  </BlockStack>
</Card>

Options with sections

Section titled “Options with sections”

Organize options into logical groups with section headers.

<script>
  import { OptionList, Card, Text, BlockStack } from 'svelte-polaris';


  let selectedOptions = ['products'];


  const sections = [
    {
      title: 'Content',
      options: [
        { value: 'products', label: 'Products' },
        { value: 'collections', label: 'Collections' },
        { value: 'pages', label: 'Pages' },
        { value: 'blog_posts', label: 'Blog posts' }
      ]
    },
    {
      title: 'Sales',
      options: [
        { value: 'orders', label: 'Orders' },
        { value: 'customers', label: 'Customers' },
        { value: 'discounts', label: 'Discounts' },
        { value: 'gift_cards', label: 'Gift cards' }
      ]
    },
    {
      title: 'Analytics',
      options: [
        { value: 'reports', label: 'Reports' },
        { value: 'live_view', label: 'Live view' },
        { value: 'dashboards', label: 'Dashboards' }
      ]
    }
  ];


  function handleChange(selected) {
    selectedOptions = selected;
  }
</script>


<Card>
  <BlockStack gap="300">
    <Text variant="headingMd">Export Data</Text>
    {#each sections as section}
      <OptionList
        title={section.title}
        options={section.options}
        selected={selectedOptions}
        onChange={handleChange}
        allowMultiple
      />
    {/each}
    <Text>Selected: {selectedOptions.join(', ')}</Text>
  </BlockStack>
</Card>

Options with descriptions

Section titled “Options with descriptions”

Provide additional context for options with descriptions.

<script>
  import { OptionList, Card, Text, BlockStack } from 'svelte-polaris';


  let selectedOptions = ['standard'];


  const options = [
    {
      value: 'express',
      label: 'Express Shipping',
      description: '1-2 business days delivery'
    },
    {
      value: 'standard',
      label: 'Standard Shipping',
      description: '3-5 business days delivery'
    },
    {
      value: 'economy',
      label: 'Economy Shipping',
      description: '7-10 business days delivery'
    },
    {
      value: 'pickup',
      label: 'Store Pickup',
      description: 'Available within 2 hours'
    }
  ];


  function handleChange(selected) {
    selectedOptions = selected;
  }
</script>


<Card>
  <BlockStack gap="300">
    <Text variant="headingMd">Shipping Options</Text>
    <OptionList
      title="Choose delivery method"
      options={options}
      selected={selectedOptions}
      onChange={handleChange}
    />
    <Text>Selected: {selectedOptions.join(', ')}</Text>
  </BlockStack>
</Card>

Props

Section titled “Props”

OptionList props

Section titled “OptionList props”
PropTypeDefaultDescription
titlestringTitle for the option list
optionsOption[][]Array of options to display
selectedstring[][]Array of selected option values
onChange(selected: string[]) => voidCallback when selection changes
allowMultiplebooleanfalseAllow multiple selections
idstringUnique identifier for the option list

Option type

Section titled “Option type”
type Option = {
  value: string;
  label: string;
  description?: string;
  disabled?: boolean;
  media?: React.ReactNode;
}

Best practices

Section titled “Best practices”
  • Use clear, descriptive labels for all options
  • Group related options together with section titles
  • Provide descriptions for options that need clarification
  • Keep option lists to a reasonable length (under 10 items when possible)
  • Use consistent language and formatting across options
  • Order options logically (alphabetical, by importance, etc.)
  • Indicate disabled options clearly and explain why they’re unavailable
  • Use single selection for mutually exclusive choices
  • Use multiple selection only when users truly need to select multiple items
  • Test with keyboard navigation to ensure accessibility

Accessibility

Section titled “Accessibility”
  • Proper ARIA attributes for list semantics
  • Keyboard navigation support (arrow keys, space, enter)
  • Screen reader announcements for selection changes
  • Focus management handles disabled options correctly
  • Selected state is clearly communicated to assistive technologies
  • Option descriptions are properly associated with labels
  • High contrast mode displays options clearly
  • Focus indicators are visible and clear
  • Multi-select state is properly announced
  • Section headers provide proper content structure

Keyboard shortcuts

Section titled “Keyboard shortcuts”
  • Arrow Up/Down: Navigate between options
  • Space: Toggle selection of focused option
  • Enter: Select focused option (single select mode)
  • Home: Move to first option
  • End: Move to last option
  • Tab: Move focus out of option list
Section titled “Related components”
  • Use Listbox for more advanced option lists with sections
  • Use Select for simple dropdown selection
  • Use ChoiceList for radio button or checkbox style selections
  • Use Combobox for searchable option lists
  • Use AutoComplete for filtered suggestions
  • Use ActionList for action-oriented lists