OptionList

When to useLink to "When to use"

• Building a new field whose choices drop down under it, so its list looks and behaves like Select's and Combobox's.

Use something else when:

• people pick one value from a list: Select
• people type to filter suggestions: Combobox
• the list is a set of actions, not values: Menu

UsageLink to "Usage"

import { OptionList, OptionListItem, OptionListNote } from "@arshad-shah/cynosure";

useListboxLayer({ anchor: field, list, open, onClose: () => setOpen(false) });

<OptionList ref={list} id={listId} label="Fruit">
  {matches.length === 0 && <OptionListNote>No matches</OptionListNote>}
  {matches.map((fruit, index) => (
    <OptionListItem
      key={fruit.value}
      id={`${listId}-${index}`}
      label={fruit.label}
      description={fruit.description}
      selected={fruit.value === value}
      active={index === active}
      disabled={fruit.disabled}
      onPointerMove={() => setActive(index)}
      onClick={() => choose(fruit)}
    />
  ))}
</OptionList>

The list is a manual popover. useListboxLayer (in src/overlay/listbox-layer.ts) shows it in the top layer, at least as wide as the field and below it, and closes it on Escape or a press outside.

Options, descriptions and notesLink to "Options, descriptions and notes"

OptionListItem takes a label, an optional description (a smaller, muted second line) and an icon drawn before the text. selected marks the chosen option, active highlights the one the arrow keys are on, and disabled fades an option and marks it aria-disabled. OptionListNote stands in for options when nothing matches or results are loading.

Trailing content, dimmed options and a footerLink to "Trailing content, dimmed options and a footer"

trailing puts a shortcut or a count at the end of an option's row, smaller and muted. dimmed draws an option muted while it stays choosable: a saved connection that is not connected, say. footer pins an action under the options, set off by a line and kept in view while the options scroll: "Manage connections…".

The footer is an option, not a separate button. The field keeps focus and points at options with aria-activedescendant, and a listbox may only hold options, so a button would be out of reach of the arrow keys and a Tab to it would close the list. As an option it is the last stop of the arrow keys, Enter runs it and a press runs it without moving focus. The list draws it from footer={{ action, id, active, onActive, onRun }}; the field that owns the list decides what choosing it does: Select and Combobox take a footer action ({ label, icon?, onSelect }), make it the last stop of useActiveOption, and close the list before running it.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Roles: the list is a listbox named by label or aria-labelledby; options are options with aria-selected; groups are groups named by their heading.
• Focus: a press on an option never moves focus: the field keeps it and points at the active option with aria-activedescendant.
• Keys: the list handles none; the field that owns it does (arrows, Enter, Escape, type-ahead).
• Loading: busy sets aria-busy.
• Footer: an option in a role="none" wrapper at the end of the listbox, after every option and group.
• Right to left: the icon leads on the right, and trailing content ends the row on the left.

TouchLink to "Touch"

Options are at least 44px tall on coarse pointers, and a tap chooses.

ThemingLink to "Theming"

Tokens: --cy-option-list-bg, --cy-option-list-shadow, --cy-option-list-max-height, --cy-option-list-max-width and --cy-option-list-active-bg. Select and Combobox set them from their own list tokens (--cy-select-list-bg, --cy-combobox-list-bg and the rest).

RelatedLink to "Related"

Select · Combobox · TagInput · Menu