Listbox

Input field that displays a list of items when selected.

styleKeys: listboxstyleKeys: popover

Listbox is only available in the React API for SWAN.

UsageGuidelinesAPI

For a better mobile experience, use Dropdown when the list contains simple text choices. Use Listbox only if you require images, sections, or other styling inside the choices.

Use Listbox...

To display complex information like titles, sections, thumbnail images or callouts.

Don't use Listbox...

To display a list with plain text. Use Dropdown instead.
To display a list with links. Use Menu instead.
To leverage the native browser select functionality.

Basic Listbox

A BasicListbox is a simple-to-use convenience component that handles most typical use cases of a Listbox.

It takes a set of ListboxOption components as children:

Each ListboxOption must have a key prop holding that option's value.
Optionally, use a label prop for each ListboxOption. This feature allows you to display specific content or have callouts in the Listbox's button element when an option is selected.

Inside each ListboxOption you can put any HTML content, including bold text, colored text, Callouts, etc. For more information, see With HTML or JSX content.

BasicListbox also needs an accessible label: either an aria-labelledby prop whose value is the id of the element on the page that labels the Listbox, or an aria-label prop whose value is localized text for the label.

<BasicListbox aria-label="Select a finish">
  <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
  <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
  <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
  <ListboxOption key="None">None</ListboxOption>
</BasicListbox>

<BasicListbox aria-label="Select a finish">
  <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
  <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
  <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
  <ListboxOption key="None">None</ListboxOption>
</BasicListbox>

Full Listbox

Use a full Listbox for more advanced features, like for instance, an inner or floating label.

You will need to include some sub-components that BasicListbox takes care of for you.

<Listbox>
  <ListboxButton aria-label="Select a finish" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox>
  <ListboxButton aria-label="Select a finish" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

Size

size is deprecated in SWAN v3.3

The component now automatically handles sizing based on the selected mode(standardMode/compactMode). Please update your implementation to rely on the new mode-based sizing.

Use size="mini" to reduce the height of a Listbox. Use also the "mini" size for components that should play a supporting role in the layout, ensuring a clear visual hierarchy. This size works well in situations where there are limitations on vertical space.

<Listbox size="mini">
  <ListboxButton aria-label="Select a finish" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox size="mini">
  <ListboxButton aria-label="Select a finish" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

Full width

Use fullWidth to grow a Listbox to fill it's container.

<Listbox fullWidth>
  <ListboxButton aria-label="Select a finish" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox fullWidth>
  <ListboxButton aria-label="Select a finish" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

Label prefix

Use labelPrefix to display a "prefix" on the left and the selected value on the right.

Note that the BasicListbox convenience component cannot be used for this purpose.

<Listbox>
  <ListboxButton labelPrefix="Finish:" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox>
  <ListboxButton labelPrefix="Finish:" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

Button placeholder

Use the placeholder property if you want to show a text when no options are selected.

<Listbox fullWidth>
  <ListboxButton labelPrefix="Quantity:" placeholder="Select a quantity" />
  <ListboxPopover>
    <ListboxList aria-label="Quantity options">
      <ListboxOption key="100">100</ListboxOption>
      <ListboxOption key="200">200</ListboxOption>
      <ListboxOption key="300">300</ListboxOption>
      <ListboxOption key="400">400</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox fullWidth>
  <ListboxButton labelPrefix="Quantity:" placeholder="Select a quantity" />
  <ListboxPopover>
    <ListboxList aria-label="Quantity options">
      <ListboxOption key="100">100</ListboxOption>
      <ListboxOption key="200">200</ListboxOption>
      <ListboxOption key="300">300</ListboxOption>
      <ListboxOption key="400">400</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

With floating label

An alternate way to display the listbox with the label positioned inside it, above the selection. To achieve that, use the component InputWithFloatingLabel.

<InputWithFloatingLabel>
  <FloatingLabel>Finish</FloatingLabel>
  <Listbox>
    <ListboxButton />
    <ListboxPopover>
      <ListboxList>
        <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
        <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
        <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
        <ListboxOption key="None">None</ListboxOption>
      </ListboxList>
    </ListboxPopover>
  </Listbox>
</InputWithFloatingLabel>

<InputWithFloatingLabel>
  <FloatingLabel>Finish</FloatingLabel>
  <Listbox>
    <ListboxButton />
    <ListboxPopover>
      <ListboxList>
        <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
        <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
        <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
        <ListboxOption key="None">None</ListboxOption>
      </ListboxList>
    </ListboxPopover>
  </Listbox>
</InputWithFloatingLabel>

With thumbnail container

Use ListboxOptionThumbnailContainer, which contains a square FluidImage, to display square thumbnail images in selections.

<Listbox>
  <ListboxButton aria-label="Select a corner style" />
  <ListboxPopover>
    <ListboxList aria-label="Corner style options">
      <ListboxOption
        key="standard"
        textValue="Standard corners"
        label="Standard corners"
        withThumbnail
      >
        <ListboxOptionThumbnailContainer>
          <FluidImage src="/example-images/1x1.webp" alt="my thumbnail" />
        </ListboxOptionThumbnailContainer>
        <ListboxOptionTextContainer>
          Traditional square corners for a crisp, clean look.
          <Typography fontSize={'-1'} textColor="dark-grey">
            Square
          </Typography>
        </ListboxOptionTextContainer>
      </ListboxOption>
      <ListboxOption
        key="rounded"
        textValue="Rounded corner business cards give you an edge with a modern, memorable look. Available with special papers and finishes."
        label="Rounded corner business cards give you an edge with a modern, memorable look. Available with special papers and finishes."
        withThumbnail
      >
        <ListboxOptionThumbnailContainer>
          <FluidImage src="/example-images/1x1-2.webp" alt="my thumbnail" />
        </ListboxOptionThumbnailContainer>
        <ListboxOptionTextContainer>
          Rounded corner business cards have a look that’s hard to miss. Not to
          mention, a soft, smooth feel in people’s hands. The attention-grabbing
          shape looks elegant and professional – but also gives your design a
          unique, modern vibe.
          <Typography fontSize={'-1'} textColor="dark-grey">
            Rounded
          </Typography>
        </ListboxOptionTextContainer>
      </ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox>
  <ListboxButton aria-label="Select a corner style" />
  <ListboxPopover>
    <ListboxList aria-label="Corner style options">
      <ListboxOption
        key="standard"
        textValue="Standard corners"
        label="Standard corners"
        withThumbnail
      >
        <ListboxOptionThumbnailContainer>
          <FluidImage src="/example-images/1x1.webp" alt="my thumbnail" />
        </ListboxOptionThumbnailContainer>
        <ListboxOptionTextContainer>
          Traditional square corners for a crisp, clean look.
          <Typography fontSize={'-1'} textColor="dark-grey">
            Square
          </Typography>
        </ListboxOptionTextContainer>
      </ListboxOption>
      <ListboxOption
        key="rounded"
        textValue="Rounded corner business cards give you an edge with a modern, memorable look. Available with special papers and finishes."
        label="Rounded corner business cards give you an edge with a modern, memorable look. Available with special papers and finishes."
        withThumbnail
      >
        <ListboxOptionThumbnailContainer>
          <FluidImage src="/example-images/1x1-2.webp" alt="my thumbnail" />
        </ListboxOptionThumbnailContainer>
        <ListboxOptionTextContainer>
          Rounded corner business cards have a look that’s hard to miss. Not to
          mention, a soft, smooth feel in people’s hands. The attention-grabbing
          shape looks elegant and professional – but also gives your design a
          unique, modern vibe.
          <Typography fontSize={'-1'} textColor="dark-grey">
            Rounded
          </Typography>
        </ListboxOptionTextContainer>
      </ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

With sections

Use ListboxSection to display a section title to wrap a group of selections. Each ListboxSection requires a title and a key prop.

<Listbox>
  <ListboxButton aria-label="Select Standard Business Cards options" />
  <ListboxPopover>
    <ListboxList aria-label="Standard Business Cards options">
      <ListboxSection title="Paper Thickness">
        <ListboxOption>Standard</ListboxOption>
        <ListboxOption>Premium</ListboxOption>
        <ListboxOption>Premium Plus</ListboxOption>
      </ListboxSection>
      <ListboxSection title="Paper Stocks">
        <ListboxOption>Mate</ListboxOption>
        <ListboxOption>Glossy</ListboxOption>
        <ListboxOption>Uncoated</ListboxOption>
        <ListboxOption>Embossed Gloss</ListboxOption>
      </ListboxSection>
      <ListboxSection title="Shapes">
        <ListboxOption>Standard</ListboxOption>
        <ListboxOption>Square</ListboxOption>
      </ListboxSection>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox>
  <ListboxButton aria-label="Select Standard Business Cards options" />
  <ListboxPopover>
    <ListboxList aria-label="Standard Business Cards options">
      <ListboxSection title="Paper Thickness">
        <ListboxOption>Standard</ListboxOption>
        <ListboxOption>Premium</ListboxOption>
        <ListboxOption>Premium Plus</ListboxOption>
      </ListboxSection>
      <ListboxSection title="Paper Stocks">
        <ListboxOption>Mate</ListboxOption>
        <ListboxOption>Glossy</ListboxOption>
        <ListboxOption>Uncoated</ListboxOption>
        <ListboxOption>Embossed Gloss</ListboxOption>
      </ListboxSection>
      <ListboxSection title="Shapes">
        <ListboxOption>Standard</ListboxOption>
        <ListboxOption>Square</ListboxOption>
      </ListboxSection>
    </ListboxList>
  </ListboxPopover>
</Listbox>

With HTML or JSX content

ListboxOption can accept inner HTML content, such as a Callout. When using HTML content, include a textValue prop whose value is an accessible label for the option.

Additionally, the label prop can be used to dictate how the selected option is rendered inside the ListboxButton.

<Listbox>
  <ListboxButton aria-label="Select a finish" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption
        key="Foil Accent"
        textValue="Foil Accent"
        label="Foil Accent"
        disabled
      >
        Foil Accent{' '}
        <Callout variant="overlay" skin="holiday">
          Sold Out!
        </Callout>
      </ListboxOption>
      <ListboxOption
        key="Embossed Gloss"
        textValue="Embossed Gloss"
        label="Embossed Gloss《New!》"
      >
        Embossed Gloss{' '}
        <Callout variant="overlay" skin="announcement">
          New!
        </Callout>
      </ListboxOption>
      <ListboxOption key="None" textValue="None" label="None">
        None{' '}
        <Callout variant="overlay" skin="promo">
          Promo!
        </Callout>
      </ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox>
  <ListboxButton aria-label="Select a finish" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption
        key="Foil Accent"
        textValue="Foil Accent"
        label="Foil Accent"
        disabled
      >
        Foil Accent{' '}
        <Callout variant="overlay" skin="holiday">
          Sold Out!
        </Callout>
      </ListboxOption>
      <ListboxOption
        key="Embossed Gloss"
        textValue="Embossed Gloss"
        label="Embossed Gloss《New!》"
      >
        Embossed Gloss{' '}
        <Callout variant="overlay" skin="announcement">
          New!
        </Callout>
      </ListboxOption>
      <ListboxOption key="None" textValue="None" label="None">
        None{' '}
        <Callout variant="overlay" skin="promo">
          Promo!
        </Callout>
      </ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

Options

Default option

By default, the Listbox displays the first option in the button, but doesn't select it until the user clicks an option: this is to mirror the behavior of an HTML select tag. To preselect an option in the Listbox, use the value prop.

<Listbox value="Embossed Gloss">
  <ListboxButton aria-label="Select a finish" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox value="Embossed Gloss">
  <ListboxButton aria-label="Select a finish" />
  <ListboxPopover>
    <ListboxList aria-label="Finish options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

Custom Listbox options

You can use any core prop from SWAN or enclose any SWAN component to create your custom Listbox Option. A very peculiar use case of this across Vista is showing Quantity and Pricing in conjunction, which can be achieved using the FlexBox component as below.

() => {
  const entries = [
    {
      qty: 25,
      unitCost: '$0.36/unit',
      total: '$12.99',
    },
    {
      qty: 50,
      unitCost: '$0.32/unit',
      total: '$22.99',
    },
    {
      qty: 100,
      unitCost: '$0.30/unit',
      total: '$42.99',
    },
  ]
  return (
    <Listbox fullWidth>
      <ListboxButton labelPrefix="Quantity:" placeholder="Select a quantity" />
      <ListboxPopover>
        <ListboxList aria-label="Select a quantity">
          {entries.map(u => (
            <ListboxOption label={u.qty} textValue={u.qty} key={u.qty}>
              <FlexBox justifyContent="space-between">
                <Box>
                  {u.qty}
                  <Span ml={1} fontSkin="body-standard-bold" textColor="promo">
                    ({u.unitCost})
                  </Span>
                </Box>
                <Box>{u.total}</Box>
              </FlexBox>
            </ListboxOption>
          ))}
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  )
}

() => {
  const entries = [
    {
      qty: 25,
      unitCost: '$0.36/unit',
      total: '$12.99',
    },
    {
      qty: 50,
      unitCost: '$0.32/unit',
      total: '$22.99',
    },
    {
      qty: 100,
      unitCost: '$0.30/unit',
      total: '$42.99',
    },
  ]
  return (
    <Listbox fullWidth>
      <ListboxButton labelPrefix="Quantity:" placeholder="Select a quantity" />
      <ListboxPopover>
        <ListboxList aria-label="Select a quantity">
          {entries.map(u => (
            <ListboxOption label={u.qty} textValue={u.qty} key={u.qty}>
              <FlexBox justifyContent="space-between">
                <Box>
                  {u.qty}
                  <Span ml={1} fontSkin="body-standard-bold" textColor="promo">
                    ({u.unitCost})
                  </Span>
                </Box>
                <Box>{u.total}</Box>
              </FlexBox>
            </ListboxOption>
          ))}
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  )
}

Options as Links

Use href on ListboxOption to make it a link.

<Listbox>
  <ListboxButton aria-label="Select Product" />
  <ListboxPopover>
    <ListboxList aria-label="Product options">
      <ListboxOption href="/business-cards">Business Cards</ListboxOption>
      <ListboxOption href="/holiday-cards">Holiday Cards</ListboxOption>
      <ListboxOption href="/postcards">Postcards</ListboxOption>

      <ListboxOption href="/t-shirts">Tshirts</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox>
  <ListboxButton aria-label="Select Product" />
  <ListboxPopover>
    <ListboxList aria-label="Product options">
      <ListboxOption href="/business-cards">Business Cards</ListboxOption>
      <ListboxOption href="/holiday-cards">Holiday Cards</ListboxOption>
      <ListboxOption href="/postcards">Postcards</ListboxOption>

      <ListboxOption href="/t-shirts">Tshirts</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

The onSelectionChange callback is incompatible with links because they are not treated as selectable items, but rather as navigation items. Instead, use onClick on ListboxList to perform any side effects upon click of an option (e.g. firing a tracking event).

<Listbox>
  <ListboxButton aria-label="Select Product" />
  <ListboxPopover>
    <ListboxList
      aria-label="Product options"
      onClick={e => {
        if (e.target instanceof HTMLAnchorElement) {
          const key = e.target.dataset.key
          console.log('🚀 Firing a tracking event for', key)
        }
      }}
    >
      <ListboxOption href="/business-cards">Business Cards</ListboxOption>
      <ListboxOption href="/holiday-cards">Holiday Cards</ListboxOption>
      <ListboxOption href="/postcards">Postcards</ListboxOption>
      <ListboxOption href="/t-shirts">Tshirts</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox>
  <ListboxButton aria-label="Select Product" />
  <ListboxPopover>
    <ListboxList
      aria-label="Product options"
      onClick={e => {
        if (e.target instanceof HTMLAnchorElement) {
          const key = e.target.dataset.key
          console.log('🚀 Firing a tracking event for', key)
        }
      }}
    >
      <ListboxOption href="/business-cards">Business Cards</ListboxOption>
      <ListboxOption href="/holiday-cards">Holiday Cards</ListboxOption>
      <ListboxOption href="/postcards">Postcards</ListboxOption>
      <ListboxOption href="/t-shirts">Tshirts</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

If the side effect is asynchronous, use preventDefault to prevent the redirect while you wait for your logic to resolve, and then manually navigate.

() => {
  const mockApiCall = key => {
    console.log('🚀 Simulating an async API call with key:', key)
    return new Promise(resolve => {
      setTimeout(() => {
        console.log('Done, redirecting...')
        resolve('API call complete')
      }, 3000)
    })
  }

  return (
    <Listbox>
      <ListboxButton aria-label="Select Product" />
      <ListboxPopover>
        <ListboxList
          aria-label="Product options"
          onClick={async e => {
            if (e.target instanceof HTMLAnchorElement) {
              // 1) Prevent the redirect
              e.preventDefault()

              // 2) Grab any metadata you need from the event
              const href = e.target.href
              const key = e.target.dataset.key
              const target = e.target.target

              // 3) Run your logic with the metadata
              await mockApiCall(key)

              // Redirect
              if (target === '_blank') {
                window.open(href, '_blank', 'noopener,noreferrer') // For new-tab navigation
              } else {
                window.location.href = href // For same-tab navigation
              }
            }
          }}
        >
          <ListboxOption href="/business-cards">Business Cards</ListboxOption>
          <ListboxOption href="/holiday-cards">Holiday Cards</ListboxOption>
          <ListboxOption href="/postcards">Postcards</ListboxOption>
          <ListboxOption href="/t-shirts">Tshirts</ListboxOption>
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  )
}

() => {
  const mockApiCall = key => {
    console.log('🚀 Simulating an async API call with key:', key)
    return new Promise(resolve => {
      setTimeout(() => {
        console.log('Done, redirecting...')
        resolve('API call complete')
      }, 3000)
    })
  }

  return (
    <Listbox>
      <ListboxButton aria-label="Select Product" />
      <ListboxPopover>
        <ListboxList
          aria-label="Product options"
          onClick={async e => {
            if (e.target instanceof HTMLAnchorElement) {
              // 1) Prevent the redirect
              e.preventDefault()

              // 2) Grab any metadata you need from the event
              const href = e.target.href
              const key = e.target.dataset.key
              const target = e.target.target

              // 3) Run your logic with the metadata
              await mockApiCall(key)

              // Redirect
              if (target === '_blank') {
                window.open(href, '_blank', 'noopener,noreferrer') // For new-tab navigation
              } else {
                window.location.href = href // For same-tab navigation
              }
            }
          }}
        >
          <ListboxOption href="/business-cards">Business Cards</ListboxOption>
          <ListboxOption href="/holiday-cards">Holiday Cards</ListboxOption>
          <ListboxOption href="/postcards">Postcards</ListboxOption>
          <ListboxOption href="/t-shirts">Tshirts</ListboxOption>
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  )
}

Multi select

You can make a Listbox a multi select by setting the selectionMode="multiple" prop. This will allow the user to select multiple items from the Listbox.

<Listbox selectionMode="multiple">
  <ListboxButton aria-label="Select addons" />
  <ListboxPopover>
    <ListboxList aria-label="Addon options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

<Listbox selectionMode="multiple">
  <ListboxButton aria-label="Select addons" />
  <ListboxPopover>
    <ListboxList aria-label="Addon options">
      <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
      <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
      <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
      <ListboxOption key="None">None</ListboxOption>
    </ListboxList>
  </ListboxPopover>
</Listbox>

Disabled

Use disabled on Listbox to prevent it from being opened.

Use disabled or disabledKeys on ListboxOption to indicate that individual options are not relevant or available within the user's current context.

<FlexBox flexWrap="wrap" gap="8">
  <Box>
    <P>Disabled listbox</P>
    <Listbox disabled>
      <ListboxButton aria-label="Select a finish" />
      <ListboxPopover>
        <ListboxList aria-label="Finish options">
          <ListboxOption>Gold Raised Foil</ListboxOption>
          <ListboxOption>Foil Accent</ListboxOption>
          <ListboxOption>Embossed Gloss</ListboxOption>
          <ListboxOption>None</ListboxOption>
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  </Box>
  <Box>
    <P>Using disabled prop on an option</P>
    <Listbox>
      <ListboxButton aria-label="Select a finish" />
      <ListboxPopover>
        <ListboxList aria-label="Finish options">
          <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
          <ListboxOption
            key="Foil Accent"
            textValue="Foil Accent"
            label="Foil Accent"
            disabled
          >
            Foil Accent{' '}
          </ListboxOption>
          <ListboxOption
            key="Embossed Gloss"
            textValue="Embossed Gloss"
            label="Embossed Gloss"
          >
            Embossed Gloss{' '}
          </ListboxOption>
          <ListboxOption key="None">None</ListboxOption>
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  </Box>
  <Box>
    <P>Using disabledKeys</P>
    <Listbox disabledKeys={new Set(['Foil Accent'])}>
      <ListboxButton aria-label="Select a finish" />
      <ListboxPopover>
        <ListboxList aria-label="Finish options">
          <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
          <ListboxOption
            key="Foil Accent"
            textValue="Foil Accent"
            label="Foil Accent"
          >
            Foil Accent{' '}
          </ListboxOption>
          <ListboxOption
            key="Embossed Gloss"
            textValue="Embossed Gloss"
            label="Embossed Gloss"
          >
            Embossed Gloss{' '}
          </ListboxOption>
          <ListboxOption key="None">None</ListboxOption>
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  </Box>
</FlexBox>

<FlexBox flexWrap="wrap" gap="8">
  <Box>
    <P>Disabled listbox</P>
    <Listbox disabled>
      <ListboxButton aria-label="Select a finish" />
      <ListboxPopover>
        <ListboxList aria-label="Finish options">
          <ListboxOption>Gold Raised Foil</ListboxOption>
          <ListboxOption>Foil Accent</ListboxOption>
          <ListboxOption>Embossed Gloss</ListboxOption>
          <ListboxOption>None</ListboxOption>
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  </Box>
  <Box>
    <P>Using disabled prop on an option</P>
    <Listbox>
      <ListboxButton aria-label="Select a finish" />
      <ListboxPopover>
        <ListboxList aria-label="Finish options">
          <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
          <ListboxOption
            key="Foil Accent"
            textValue="Foil Accent"
            label="Foil Accent"
            disabled
          >
            Foil Accent{' '}
          </ListboxOption>
          <ListboxOption
            key="Embossed Gloss"
            textValue="Embossed Gloss"
            label="Embossed Gloss"
          >
            Embossed Gloss{' '}
          </ListboxOption>
          <ListboxOption key="None">None</ListboxOption>
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  </Box>
  <Box>
    <P>Using disabledKeys</P>
    <Listbox disabledKeys={new Set(['Foil Accent'])}>
      <ListboxButton aria-label="Select a finish" />
      <ListboxPopover>
        <ListboxList aria-label="Finish options">
          <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
          <ListboxOption
            key="Foil Accent"
            textValue="Foil Accent"
            label="Foil Accent"
          >
            Foil Accent{' '}
          </ListboxOption>
          <ListboxOption
            key="Embossed Gloss"
            textValue="Embossed Gloss"
            label="Embossed Gloss"
          >
            Embossed Gloss{' '}
          </ListboxOption>
          <ListboxOption key="None">None</ListboxOption>
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  </Box>
</FlexBox>

Managing state

As is the case with most form elements, folks often want to "control" this component. Controlling a component means that you take ownership over its state rather than letting the browser manage the state for you. When you control a component, you own the source of truth for the UI. This means that you don't need to query the DOM in order to determine the current value of the element. So, when it comes time to use the value of the element somewhere else (e.g. submitting the selection to a back-end service) you can trust your stored value.

To control a Listbox, store the selected value (e.g., in React state or a Redux store) and provide a handler to update this value when users interact with the component.

() => {
  const [selected, setSelected] = React.useState(new Set(['Default']))
  return (
    <>
      <p>Selected value: {selected}</p>
      <Listbox selectedKeys={selected} onSelectionChange={setSelected}>
        <ListboxButton aria-label="Select a finish" />
        <ListboxPopover>
          <ListboxList aria-label="Finish options">
            <ListboxOption key="Default">Gold Raised Foil</ListboxOption>
            <ListboxOption key="Finish 2" textValue="Foil Accent option">
              Foil Accent
            </ListboxOption>
            <ListboxOption key="Finish 3" textValue="Embossed Gloss option">
              Embossed Gloss
            </ListboxOption>
            <ListboxOption key="No finish" textValue="None">
              None
            </ListboxOption>
          </ListboxList>
        </ListboxPopover>
      </Listbox>
    </>
  )
}

() => {
  const [selected, setSelected] = React.useState(new Set(['Default']))
  return (
    <>
      <p>Selected value: {selected}</p>
      <Listbox selectedKeys={selected} onSelectionChange={setSelected}>
        <ListboxButton aria-label="Select a finish" />
        <ListboxPopover>
          <ListboxList aria-label="Finish options">
            <ListboxOption key="Default">Gold Raised Foil</ListboxOption>
            <ListboxOption key="Finish 2" textValue="Foil Accent option">
              Foil Accent
            </ListboxOption>
            <ListboxOption key="Finish 3" textValue="Embossed Gloss option">
              Embossed Gloss
            </ListboxOption>
            <ListboxOption key="No finish" textValue="None">
              None
            </ListboxOption>
          </ListboxList>
        </ListboxPopover>
      </Listbox>
    </>
  )
}

If you don't need to manage the state of the Listbox, you can omit the selectedKeys and onSelectionChange props, allowing the browser to handle the state. Consider using the value prop to specify the initial selected value.

Dynamic Collections

Use the Dynamics Collections API with a render function as the child of ListboxList for better performance with large or dynamic data.

To use the API, pass an array into the items prop of the Listbox. Be sure to keep the items reference stable, by storing it in state or using useMemo, when the data isn’t changing.

() => {
  const items = React.useMemo(
    () => [
      { qty: 100, text: '100 ($0.18 / unit)' },
      { qty: 250, text: '250 ($0.10 / unit)' },
      { qty: 500, text: '500 ($0.06 / unit)', recommended: true },
      { qty: 1000, text: '1000 ($0.05 / unit)' },
      { qty: 1500, text: '1500 ($0.04 / unit)' },
      { qty: 2000, text: '2000 ($0.04 / unit)' },
      { qty: 2500, text: '2500 ($0.04 / unit)' },
      { qty: 5000, text: '5000 ($0.03 / unit)' },
      { qty: 10000, text: '10000 ($0.03 / unit)' },
    ],
    [],
  )

  return (
    <Listbox items={items}>
      <ListboxButton aria-label="Select your quantity" />
      <ListboxPopover>
        <ListboxList aria-label="Quantity options">
          {item => (
            <ListboxOption
              key={item.qty}
              textValue={item.text}
              label={`${item.text} ${
                item.recommended ? '《Recommended!》' : ''
              }`}
            >
              {item.text}{' '}
              {item.recommended ? (
                <Callout size="mini" skin="announcement">
                  Recommended
                </Callout>
              ) : null}
            </ListboxOption>
          )}
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  )
}

() => {
  const items = React.useMemo(
    () => [
      { qty: 100, text: '100 ($0.18 / unit)' },
      { qty: 250, text: '250 ($0.10 / unit)' },
      { qty: 500, text: '500 ($0.06 / unit)', recommended: true },
      { qty: 1000, text: '1000 ($0.05 / unit)' },
      { qty: 1500, text: '1500 ($0.04 / unit)' },
      { qty: 2000, text: '2000 ($0.04 / unit)' },
      { qty: 2500, text: '2500 ($0.04 / unit)' },
      { qty: 5000, text: '5000 ($0.03 / unit)' },
      { qty: 10000, text: '10000 ($0.03 / unit)' },
    ],
    [],
  )

  return (
    <Listbox items={items}>
      <ListboxButton aria-label="Select your quantity" />
      <ListboxPopover>
        <ListboxList aria-label="Quantity options">
          {item => (
            <ListboxOption
              key={item.qty}
              textValue={item.text}
              label={`${item.text} ${
                item.recommended ? '《Recommended!》' : ''
              }`}
            >
              {item.text}{' '}
              {item.recommended ? (
                <Callout size="mini" skin="announcement">
                  Recommended
                </Callout>
              ) : null}
            </ListboxOption>
          )}
        </ListboxList>
      </ListboxPopover>
    </Listbox>
  )
}

Accessibility

BasicListbox requires an aria-labelledby attribute (preferred) or aria-label attribute.

ListboxList requires an aria-label attribute (do not use aria-labelledby , it is not supported).

ListboxButton accepts an aria-labelledby attribute or aria-label attribute, but neither are required because an accessible name will be assigned by default.

<FlexBox flexDirection="column" gap={8}>
  {/* Example of a visible label with BasicListbox*/}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of a visible label with BasicListbox
    </Typography>
    <FlexBox gap="2" flexDirection="column">
      <Span id="label-example-1">Select a finish</Span>
      <BasicListbox aria-labelledby="label-example-1">
        <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
        <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
        <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
        <ListboxOption key="None">None</ListboxOption>
      </BasicListbox>
    </FlexBox>
  </FlexBox>

  {/* Example of a non-visible label with BasicListbox*/}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of a non-visible label with BasicListbox
    </Typography>
    <FlexBox gap="2" flexDirection="column">
      <Span>With an aria-label</Span>
      <BasicListbox aria-label="Select a finish">
        <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
        <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
        <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
        <ListboxOption key="None">None</ListboxOption>
      </BasicListbox>
    </FlexBox>
  </FlexBox>

  {/* Example of a visible label with Listbox*/}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of a visible label with Listbox
    </Typography>
    <FlexBox gap="2" flexDirection="column">
      <Span id="label-example-2">Select a finish</Span>
      <Listbox>
        <ListboxButton aria-labelledby="label-example-2" />
        <ListboxPopover>
          <ListboxList aria-label="Finish options">
            <ListboxOption key="Gold Raised Foil">
              Gold Raised Foil
            </ListboxOption>
            <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
            <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
            <ListboxOption key="None">None</ListboxOption>
          </ListboxList>
        </ListboxPopover>
      </Listbox>
    </FlexBox>
  </FlexBox>

  {/* Example of a non-visible label with Listbox*/}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of a non-visible label with Listbox
    </Typography>
    <FlexBox gap="2" flexDirection="column">
      <Span>With an aria-label</Span>
      <Listbox>
        <ListboxButton aria-label="Select a finish" />
        <ListboxPopover>
          <ListboxList aria-label="Finish options">
            <ListboxOption key="Gold Raised Foil">
              Gold Raised Foil
            </ListboxOption>
            <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
            <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
            <ListboxOption key="None">None</ListboxOption>
          </ListboxList>
        </ListboxPopover>
      </Listbox>
    </FlexBox>
  </FlexBox>
</FlexBox>

<FlexBox flexDirection="column" gap={8}>
  {/* Example of a visible label with BasicListbox*/}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of a visible label with BasicListbox
    </Typography>
    <FlexBox gap="2" flexDirection="column">
      <Span id="label-example-1">Select a finish</Span>
      <BasicListbox aria-labelledby="label-example-1">
        <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
        <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
        <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
        <ListboxOption key="None">None</ListboxOption>
      </BasicListbox>
    </FlexBox>
  </FlexBox>

  {/* Example of a non-visible label with BasicListbox*/}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of a non-visible label with BasicListbox
    </Typography>
    <FlexBox gap="2" flexDirection="column">
      <Span>With an aria-label</Span>
      <BasicListbox aria-label="Select a finish">
        <ListboxOption key="Gold Raised Foil">Gold Raised Foil</ListboxOption>
        <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
        <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
        <ListboxOption key="None">None</ListboxOption>
      </BasicListbox>
    </FlexBox>
  </FlexBox>

  {/* Example of a visible label with Listbox*/}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of a visible label with Listbox
    </Typography>
    <FlexBox gap="2" flexDirection="column">
      <Span id="label-example-2">Select a finish</Span>
      <Listbox>
        <ListboxButton aria-labelledby="label-example-2" />
        <ListboxPopover>
          <ListboxList aria-label="Finish options">
            <ListboxOption key="Gold Raised Foil">
              Gold Raised Foil
            </ListboxOption>
            <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
            <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
            <ListboxOption key="None">None</ListboxOption>
          </ListboxList>
        </ListboxPopover>
      </Listbox>
    </FlexBox>
  </FlexBox>

  {/* Example of a non-visible label with Listbox*/}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of a non-visible label with Listbox
    </Typography>
    <FlexBox gap="2" flexDirection="column">
      <Span>With an aria-label</Span>
      <Listbox>
        <ListboxButton aria-label="Select a finish" />
        <ListboxPopover>
          <ListboxList aria-label="Finish options">
            <ListboxOption key="Gold Raised Foil">
              Gold Raised Foil
            </ListboxOption>
            <ListboxOption key="Foil Accent">Foil Accent</ListboxOption>
            <ListboxOption key="Embossed Gloss">Embossed Gloss</ListboxOption>
            <ListboxOption key="None">None</ListboxOption>
          </ListboxList>
        </ListboxPopover>
      </Listbox>
    </FlexBox>
  </FlexBox>
</FlexBox>

Number of listed items

A Listbox containing numerous options or only a few can be overwhelming, difficult to navigate, and may introduce unnecessary challenges by concealing information that could be easily visible.

Do

Use a Listbox when listing 5 or more items.

Dont

Use a Listbox when listing fewer than 4 items. Use a Selection Set of Radio Buttons instead, if space permits

Dont

Use a Listbox when listing more than 15 items. This can create a lack of overview and potential scrolling issues. Use a Combobox instead.

Placement

The Listbox prioritizes usability through generous padding and a large font, resulting in a minimum width determined by the widest option within the Listbox.

Ensure the Listbox has sufficient room for rendering on the page.
Account for the possibility of translated text being longer than English text to prevent display issues.

Props

BasicListbox

This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.