Listbox - Web

For development, import Listbox from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Listbox consists of four primary elements that work together to allow users to select one or more items from a list of options.

Option
Group divider
Group header
Selected option

Options

The Listbox supports grouping and multiple selection configurations to accommodate various selection scenarios.

Grouping

Multiple selection

Behavior

The Listbox responds to user interaction with typeahead focus functionality and overflow handling.

Typeahead focus

When the Listbox is in focus, a user can type a character to move focus to the next item that starts with that character. If typed quickly (750ms), focus will move to the next item that matches the string of characters typed.

Overflow handling

Visual States

Usage Guidelines

Standard	Requirement
DoProvide selectable items in an overlay	Listboxes are used as a set of selectable items in an overlay. It is most commonly used for the options in a Combobox or when building a custom menu.

Alternatives

Listbox vs List View

Use Listbox when using simple selections that do not require any customization. Use List View when requiring customized styling or secondary actions. List View may also be used when emphasizing to users that multi-selection is possible.

Listbox vs Radio

For simple selection lists in a form, use a Radio. For selection lists that need to be an overlay, use a Listbox with a Combobox.

Content

Content within the Listbox should clearly communicate each option through descriptive labels.

Keyboard Interaction

Users can navigate the Listbox using standard keyboard controls.

Key	Description
Tab	Moves to the next tab-able element outside of the Listbox.
Arrow keys	Navigates through the available list items
Space	Activates or deactivates the focused Listbox item.
Home	Moves focus to the first item in the Listbox.
End	Moves focus to the last item in the Listbox.
Printable character	Moves focus to the next item that has the character typed. If multiple characters are typed quickly (<750ms), focus moves to the next item with that combination of characters. If the next character takes longer than 750ms, focus is moved to the next item that starts with the new character typed.

Accessibility

Listbox provides all of the necessary accessibility functionality.

Don’t add additional interactive elements to the Listbox

The Listbox is designed for simple interactions, and cannot handle additional interactions, such as secondary actions. If designing for this, consider adopting similar accessibility guidance found in W3C ARIA’s Data Grid pattern. For more guidance on building accessible interactive lists, see custom components best practices.

Code

Implementation
Single-select Listbox Props
Multi-select Listbox Props
Listbox.Option Props

Common Examples

import { Listbox } from "@servicetitan/anvil2";

const ExampleComponent = () => {
  const itemsArray = [
    { id: 0, label: "First item" },
    // ... more items
  ];

  return (
    <Listbox items={itemsArray}>
      {({ items }) =>
        items.map((item) => (
          <Listbox.Option key={item.label} item={item}>
            {item.label}
          </Listbox.Option>
        ))
      }
    </Listbox>
  );
};

Listbox Components

A listbox can be created using the Listbox component and its two sub-components:

Listbox.Option: used to render the individual list options.
Listbox.OptionGroup: optionally used to group listbox options.

Single-select `Listbox` using labels only

<Listbox
  selectionMode="single"
  defaultSelected="option-1"
  selected="option-1"
  disableAutoSelectOnFocus={false}
  onSelectionChange={(selected) => console.log(selected)}
>
  <Listbox.Option label="Option 1" value="option-1" />
  <Listbox.Option label="Option 2" value="option-2" />
</Listbox>

The Listbox component can accept any valid HTML ul props, with the exception that children could change depending on whether items is supplied.

ReactNode

string

boolean

(selected: string | undefined) => void

string

"multiple" | "single"

default:"single"

See other tables for changes in types for "multiple"

Single-select `Listbox` using `items` array

<Listbox
  items={itemsArray}
  selectionMode="single"
  defaultSelected={itemsArray[0]}
  selected={itemsArray[0]}
  disableAutoSelectOnFocus={false}
  onSelectionChange={(selected) => console.log(selected)}
>
  {({ items }) =>
    items.map((item) => (
      <Listbox.Option key={item.id} item={item}>
        {item.label}
      </Listbox.Option>
    ))
  }
</Listbox>

T represents any arbitrary type used for the items, and ListboxItemType<T> implies that it will include a label: string property.

({ items }: { items: ListboxItemType<T>[] }) => ReactNode

ListboxItemType<T>

boolean

ListboxItemType<T>[]

(selected: ListboxItemType<T> | undefined) => void

ListboxItemType<T>

"multiple" | "single"

default:"single"

See other tables for changes in types for "multiple"

Multi-select `Listbox` using labels only

<Listbox
  selectionMode="multiple"
  defaultSelected={["option-1", "option-2"]}
  selected={["option-1", "option-2"]}
  onSelectionChange={(selected) => console.log(selected)}
>
  <Listbox.Option label="Option 1" value="option-1" />
  <Listbox.Option label="Option 2" value="option-2" />
</Listbox>

ReactNode

string[]

(selected: string[] | undefined) => void

string[]

"multiple" | "single"

default:"multiple"

See other tables for changes in types for "single"

Multi-select `Listbox` using `items` array

<Listbox
  items={itemsArray}
  selectionMode="multiple"
  defaultSelected={[itemsArray[0], itemsArray[1]]}
  selected={[itemsArray[0], itemsArray[1]]}
  onSelectionChange={(selected) => console.log(selected)}
>
  {({ items }) =>
    items.map((item) => (
      <Listbox.Option key={item.id} item={item}>
        {item.label}
      </Listbox.Option>
    ))
  }
</Listbox>

T represents any arbitrary type used for the items, and ListboxItemType<T> implies that it will include a label: string property.

({ items }: { items: ListboxItemType<T>[] }) => ReactNode

ListboxItemType<T>[]

(selected: ListboxItemType<T>[] | undefined) => void

ListboxItemType<T>[]

"multiple" | "single"

default:"multiple"

See other tables for changes in types for "single"

<Listbox.Option item={item} label="Option 1" value="option-1" disabled={false}>
  Option content
</Listbox.Option>

`Listbox.Option` Props

In addition to the props listed below, the Listbox.Option component can accept any valid HTML li props.

boolean

{ label: string; [key: string]: unknown; }

Use with items prop on parent Listbox

string

Required if no item provided

string

Concepts & Guidelines

Anvil2

Resources

Listbox - Web

Anatomy

Options

Grouping

Multiple selection

Behavior

Typeahead focus

Overflow handling

Visual States

Usage Guidelines

Alternatives

Listbox vs List View

Listbox vs Radio

Content

Keyboard Interaction

Accessibility

Don’t add additional interactive elements to the Listbox

Code

Common Examples

Listbox Components

Single-select `Listbox` using labels only

Single-select `Listbox` using `items` array

Multi-select `Listbox` using labels only

Multi-select `Listbox` using `items` array

`Listbox.Option` Props

​Anatomy

​Options

​Grouping

​Multiple selection

​Behavior

​Typeahead focus

​Overflow handling

​Visual States

​Usage Guidelines

​Alternatives

​Listbox vs List View

​Listbox vs Radio

​Content

​Keyboard Interaction

​Accessibility

​Don’t add additional interactive elements to the Listbox

​Code

​Common Examples

​Listbox Components

​Single-select Listbox using labels only

​Single-select Listbox using items array

​Multi-select Listbox using labels only

​Multi-select Listbox using items array

​Listbox.Option Props

Anatomy

Options

Grouping

Multiple selection

Behavior

Typeahead focus

Overflow handling

Visual States

Usage Guidelines

Alternatives

Listbox vs List View

Listbox vs Radio

Content

Keyboard Interaction

Accessibility

Don’t add additional interactive elements to the Listbox

Code

Common Examples

Listbox Components

Single-select `Listbox` using labels only

Single-select `Listbox` using `items` array

Multi-select `Listbox` using labels only

Multi-select `Listbox` using `items` array

`Listbox.Option` Props