Listbox Primitive

An unstyled and accessible basis upon which to build listboxes.

Version 3.0.1

const DefaultExample = () => {
  const [items] = React.useState(['Item 1', 'Item 2', 'Item 3']);
  const [selected, setSelected] = React.useState();
  const listbox = useListboxPrimitiveState();
  return (
    <ListboxPrimitive {...listbox} aria-label="My listbox">
      <Stack orientation="vertical" spacing="space0">
        {items.map((item) => (
          <ListboxPrimitiveItem
            key={item}
            {...listbox}
            selected={selected === item}
            onSelect={() => {
              setSelected(item);
            }}
            style={{
              ...(selected === item && {backgroundColor: '#0263e0', color: 'white'})
            }}
          >
            {item}
          </ListboxPrimitiveItem>
        ))}
      </Stack>
    </ListboxPrimitive>
  )
};

render(
  <DefaultExample />
)

Guidelines

About the Listbox Primitive

The Listbox primitive is an unstyled, functional version of a listbox component. It can be used to build a component following the WAI-ARIA Listbox Pattern.

This unstyled primitive is to be used when the listbox components, like FormPillGroup, provided by Paste don’t meet the requirements needed to solve a unique customer problem. At that point, you are welcome to fall back to this functional primitive to roll your own styled Listbox while still providing a functional and accessible experience to your customers.

This primitive should be used to compose all custom Listboxes to ensure accessibility and upgrade paths.

(warning)

Before you roll your own listboxes...

We strongly suggest that all components built on top of this primitive get reviewed by the Design Systems team and go through the UX Review process to ensure an excellent experience for our customers.

Examples

Selection

To make items inside the Listbox selectable, you can manage the selection state yourself and combine it with the state returned from the useListboxPrimitiveState hook. To do so, track which item is selected in a separate store of state. When rendering the Listbox, cross reference the rendered items with the selection state, and conditionally set selected on each ListboxPrimitiveItem that requires it.

The onSelect event handler will fire whenever the item is clicked, or the spacebar or enter key is pressed. Use this to respond to your users' selection interactions.

Horizontal Listbox

Our listbox is vertical by default. To change it to horizontal, specify the orientation when initializing the state with useListboxPrimitiveState({orientation: 'horizontal'}):

const HorizontalExample = () => {
  const [items] = React.useState(['Item 1', 'Item 2', 'Item 3']);
  const [selected, setSelected] = React.useState();
  const listbox = useListboxPrimitiveState({orientation: 'horizontal'});
  return (
    <ListboxPrimitive {...listbox} aria-label="My listbox">
      {items.map((item) => (
        <ListboxPrimitiveItem
          key={item}
          {...listbox}
          selected={selected === item}
          onSelect={() => {
            setSelected(item);
          }}
          style={{
            ...(selected === item && {backgroundColor: '#0263e0', color: 'white'})
          }}
        >
          {item}
        </ListboxPrimitiveItem>
      ))}
    </ListboxPrimitive>
  )
};

render(
  <HorizontalExample />
)

Listbox with groups

Use ListboxPrimitiveGroup to create different groupings within the same listbox:

const GroupsExample = () => {
  const [items] = React.useState(['Item 1', 'Item 2', 'Item 3']);
  const [selected, setSelected] = React.useState();
  const listbox = useListboxPrimitiveState();
  return (
    <ListboxPrimitive {...listbox} aria-label="My listbox">
      <ListboxPrimitiveGroup aria-labelledby="group-1">
        <Stack orientation="vertical" spacing="space0">
          <span id="group-1">Even</span>
          {items.filter((item, index) => (index + 1) % 2 === 0).map((item) =>
            <ListboxPrimitiveItem
              key={item}
              {...listbox}
              selected={selected === item}
              onSelect={() => {
                setSelected(item);
              }}
              style={{
                ...(selected === item && {backgroundColor: '#0263e0', color: 'white'})
              }}
            >
              {item}
            </ListboxPrimitiveItem>
          )}
        </Stack>
      </ListboxPrimitiveGroup>
      <ListboxPrimitiveGroup aria-labelledby="group-2">
        <Stack orientation="vertical" spacing="space0">
          <span id="group-2">Odd</span>
          {items.filter((item, index) => (index + 1) % 2 === 1).map((item) =>
            <ListboxPrimitiveItem
              key={item}
              {...listbox}
              selected={selected === item}
              onSelect={() => {
                setSelected(item);
              }}
              style={{
                ...(selected === item && {backgroundColor: '#0263e0', color: 'white'})
              }}
            >
              {item}
            </ListboxPrimitiveItem>
          )}
        </Stack>
      </ListboxPrimitiveGroup>
    </ListboxPrimitive>
  )
};

render(
  <GroupsExample />
)

Multiselect Listbox

Our listbox is set for single selection by default. To change it to allow multiple selections, specify the variant as multiple on ListboxPrimitive:

const MultipleExample = () => {
  const [items] = React.useState(['Item 1', 'Item 2', 'Item 3']);
  const [selectedSet, updateSelectedSet] = React.useState(new Set());
  const listbox = useListboxPrimitiveState({orientation: 'horizontal'});
  return (
    <ListboxPrimitive {...listbox} aria-label="My listbox" variant="multiple">
      {items.map((item) => (
        <ListboxPrimitiveItem
          key={item}
          {...listbox}
          selected={selectedSet.has(item)}
          onSelect={() => {
            const newSelectedSet = new Set(selectedSet);
            if (newSelectedSet.has(item)) {
              newSelectedSet.delete(item);
            } else {
              newSelectedSet.add(item);
            }
            updateSelectedSet(newSelectedSet);
          }}
          style={{
            ...(selectedSet.has(item) && {backgroundColor: '#0263e0', color: 'white'})
          }}
        >
          {item}
        </ListboxPrimitiveItem>
      ))}
    </ListboxPrimitive>
  )
};

render(
  <MultipleExample />
)

Dual Listboxes

Listboxes can be used in any situation where a user needs to select items in a list or rearrange a list. One example is a UI where users need to move items between two lists like this:

const DualExample = () => {
  const [components, updateComponents] = React.useState(['Alert', 'Anchor', 'Button', 'Card', 'Heading', 'List']);
  const [favs, updateFavs] = React.useState(['Modal']);
  const [selectedComps, updateSelectedComps] = React.useState(new Set());
  const [selectedFavs, updateSelectedFavs] = React.useState(new Set());
  const compListbox = useListboxPrimitiveState();
  const favListbox = useListboxPrimitiveState();
  return (
    <Grid gutter="space30">
      <Column>
        <ListboxPrimitive {...compListbox} aria-label="Components" variant="multiple" as={Box} height="300px">
          <Stack orientation="vertical" spacing="space40">
            {components.map((item) => (
              <ListboxPrimitiveItem
                as={Button}
                size="small"
                key={item}
                {...compListbox}
                selected={selectedComps.has(item)}
                onSelect={() => {
                  const newSelectedComps = new Set(selectedComps);
                  if (newSelectedComps.has(item)) {
                    newSelectedComps.delete(item);
                  } else {
                    newSelectedComps.add(item);
                  }
                  updateSelectedComps(newSelectedComps);
                }}
              >
                {selectedComps.has(item) && <CheckboxCheckIcon decorative />}
                {item}
              </ListboxPrimitiveItem>
            ))}
          </Stack>
        </ListboxPrimitive>
        <Button variant="primary_icon" onClick={() => {
          updateFavs([...favs, ...Array.from(selectedComps)]);
          updateComponents(components.filter((item) => !selectedComps.has(item)));
          selectedComps.clear();
        }}
        >
          Add <PlusIcon decorative={false} title="Add items" />
        </Button>
      </Column>
      <Column>
        <ListboxPrimitive {...favListbox} aria-label="Favorite components" variant="multiple" as={Box} height="300px">
          <Stack orientation="vertical" spacing="space40">
            {favs.map((item) => (
              <ListboxPrimitiveItem
                as={Button}
                size="small"
                key={item}
                {...favListbox}
                selected={selectedFavs.has(item)}
                onSelect={() => {
                  const newSelectedFavs = new Set(selectedFavs);
                  if (newSelectedFavs.has(item)) {
                    newSelectedFavs.delete(item);
                  } else {
                    newSelectedFavs.add(item);
                  }
                  updateSelectedFavs(newSelectedFavs);
                }}
              >
                {selectedFavs.has(item) && <CheckboxCheckIcon decorative />}
                {item}
              </ListboxPrimitiveItem>
            ))}
          </Stack>
        </ListboxPrimitive>
        <Button variant="primary_icon" onClick={() => {
          updateComponents([...components, ...Array.from(selectedFavs)]);
          updateFavs(favs.filter((item) => !selectedFavs.has(item)));
          selectedFavs.clear();
        }}
        >
          Remove <MinusIcon decorative={false} title="Remove items" />
        </Button>
      </Column>
    </Grid>
  )
};

render(
  <DualExample />
)

Custom styling

You can provide custom styling to the primitive listbox by utilizing the as prop on each component.

The listbox primitive does not come with any styling, and thus you could mix the functionality of it with another component by using the as prop. By doing so, you can get styling from another component, and listbox functionality from this primitive.

Because these are not styled, rendering any of them as another component you can mix the functionality of two components together. Styling from one, listbox functionlity from the primitive component.

In the example below, we import the Paste Button import {Button} from '@twilio-paste/button'; and use it as the Listbox items via the as prop.

const CustomExample = () => {
  const [items] = React.useState(['Item 1', 'Item 2', 'Item 3']);
  const [selected, setSelected] = React.useState();
  const listbox = useListboxPrimitiveState({orientation: 'horizontal'});
  return (
    <ListboxPrimitive {...listbox} aria-label="My listbox">
      <Stack orientation="horizontal" spacing="space40">
      {items.map((item) => (
        <ListboxPrimitiveItem
          as={Button}
          key={item}
          {...listbox}
          selected={selected === item}
          onSelect={() => {
            setSelected(item);
          }}
        >
          {selected === item && <CheckboxCheckIcon decorative />}
          {item}
        </ListboxPrimitiveItem>
      ))}
      </Stack>
    </ListboxPrimitive>
  )
};

render(
  <CustomExample />
)

Usage Guide

This package is a wrapper around the Reakit Composite. If you’re wondering why we wrapped that package into our own, we reasoned that it would be best for our consumers’ developer experience. For example:

If we want to migrate the underlying nuts and bolts in the future, Twilio products that depend on this primitive would need to replace all occurrences of import … from ‘x-package’ to import … from ‘@some-new/package’. By wrapping it in @twilio-paste/x-primitive, this refactor can be avoided. The only change would be a version bump in the ‘package.json` file for the primitive.
We can more strictly enforce semver and backwards compatibility than some of our dependencies.
We can control when to provide an update and which versions we allow, to help reduce potential bugs our consumers may face.
We can control which APIs we expose. For example, we may chose to enable or disable usage of certain undocumented APIs.

API

Installation

yarn add @twilio-paste/listbox-primitive - or - yarn add @twilio-paste/core

Props

This props list is a scoped version of the properties available from the Reakit Composite package.

useListboxPrimitiveState

Prop	Type	Description	Default
`baseId?`	`string`	ID that will serve as a base for all the items IDs
`rtl?`	`boolean`	Determines how next and previous functions will behave
`orientation?`	`"horizontal" \\| "vertical"`	Defines the orientation of the listbox	"vertical"`
`currentId?`	`string`	The current focused item id

ListboxPrimitive

Note: Most required props are provided by spreading the returned state from useListboxPrimitiveState.

Prop	Type	Description	Default
`move`	`(id: string \\| null) => void`	Moves focus to a given item ID
`first`	`() => void`	Moves focus to the first item
`last`	`() => void`	Moves focus to the last item
`items`	`Item[]`	Lists all the listbox items with their id, DOM ref, disabled state and groupId if any. It is updated when registerItem and unregisterItem are called.
`setCurrentId`	`Dispatch<SetStateAction<string \\| null \\| undefined>>`	Sets currentId. It only updates the currentId state without moving focus.
`focusable?`	`boolean`	When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.
`disabled?`	`boolean`	Same as the HTML attribute
`baseId?`	`string`	ID that will serve as a base for all the items IDs
`currentId?`	`string`	The current focused item id
`groups?`	`Group[]`	Lists all the composite groups with their id and DOM ref. It is updated when registerGroup and unregisterGroup are called.
`orientation?`	`"horizontal" \\| "vertical"`	Defines the orientation of the listbox	"vertical"`
`variant?`	`"single" \\| "multiple"`	Defines the selection mode of the listbox	"single"`

ListboxPrimitiveGroup

No props to show

ListboxPrimitiveItem

Note: Most required props are provided by spreading the returned state from useListboxPrimitiveState.

Prop	Type	Description	Default
`baseId`	`string`	ID that will serve as a base for all the items IDs
`setBaseId`	`Dispatch<SetStateAction<string>>`	Sets the baseId
`items`	`Item[]`	Lists all the listbox items with their id, DOM ref, disabled state and groupId if any. It is updated when registerItem and unregisterItem are called.
`groups`	`Group[]`	Lists all the composite groups with their id and DOM ref. It is updated when registerGroup and unregisterGroup are called.
`rtl`	`boolean`	Determines how next and previous functions will behave
`loop`	`boolean \\| "horizontal" \\| "vertical"`	Determines how the keyboard navigation loops through the items	`'horizontal'`
`registerItem`	`(item: Item) => void`	Registers a composite item.
`unregisterItem`	`(item: Item) => void`	Unregisters a composite item.
`registerGroup`	`(group: Group) => void`	Registers a composite group.
`unregisterGroup`	`(group: Group) => void`	Unregisters a composite group.
`move`	`(id: string \\| null) => void`	Moves focus to a given item ID
`next`	`() => void`	Moves focus to the next item
`previous`	`() => void`	Moves focus to the previous item
`up`	`() => void`	Moves focus to the item above
`down`	`() => void`	Moves focus to the item below
`first`	`() => void`	Moves focus to the first item
`last`	`() => void`	Moves focus to the last item
`sort`	`() => void`	Sorts the items based on their position in the DOM
`setRTL`	`Dispatch<SetStateAction<boolean>>`	Sets rtl
`setOrientation`	`Dispatch<SetStateAction<boolean \\| "horizontal" \\| "vertical">>`	Sets orientation
`setCurrentId`	`Dispatch<SetStateAction<string \\| null \\| undefined>>`	Sets currentId. It only updates the currentId state without moving focus.
`setLoop`	`Dispatch<SetStateAction<boolean \\| "horizontal" \\| "vertical">>`	Sets loop
`reset`	`() => void`	Resets to the initial state
`selected?`	`boolean`	Set if an item is in a selected state
`disabled?`	`boolean`	Set if an item is disabled
`onSelect?`	`() => void`	Event handler called when an item is selected
`currentId?`	`string`	The current focused item id
`orientation?`	`"horizontal" \\| "vertical"`	Defines the orientation of the listbox	"vertical"`

Listbox Primitive

Guidelines

About the Listbox Primitive

Before you roll your own listboxes...

Examples

Selection

Horizontal Listbox

Listbox with groups

Multiselect Listbox

Dual Listboxes

Custom styling

Usage Guide

API

Installation

Props

useListboxPrimitiveState

ListboxPrimitive

ListboxPrimitiveGroup

ListboxPrimitiveItem

Changelog

3.0.1

Patch Changes

3.0.0

Major Changes

Patch Changes

2.0.0

Major Changes

Patch Changes

1.0.0

Major Changes