Skip to contentKino
Skip to Content

Listbox

A list of options that stays in view, for picking one or many with the pointer or the keys.

npx shadcn add https://kinoui.com/r/listbox.json
Share on

Examples

AOAmara OkaforLead
KWKenji WatanabeEngineer
LFLucía FernándezDesigner
TLTobias LindqvistProduct
MCMaya ChenEngineer
TATomás AlvarezSupport

New issues in Checkout go to this person.

Default

Press an option to pick it. Arrows, Home, End and typing a name move through the list; Space or Enter picks. In a Field, the list takes its label, description, error and disabled state.

Labels in this view

3 of 6 labels. Docs is managed by the docs team.

Bug24
Feature61
Design18
Performance9
Security4
Docs12

Multiple

With multiple, a press or Space adds an option or takes it away. Shift with a press or Space picks the options in between, Shift with an arrow carries the pick along, and Ctrl+A or ⌘A picks them all.

Time zone

Due dates and the weekly digest follow it.

Americas
Los AngelesUTC−08:00
ChicagoUTC−06:00
New YorkUTC−05:00
São PauloUTC−03:00
Europe
LisbonUTC+00:00
LondonUTC+00:00
StockholmUTC+01:00
IstanbulUTC+03:00
Asia and Pacific
SingaporeUTC+08:00
TokyoUTC+09:00
SydneyUTC+11:00

Groups

Options under a heading go in a ListboxGroup. Give the list a max-h- and it scrolls, keeping the option with focus in view.

Reviewers

Each pull request in Checkout asks them for a review.

Empty

ListboxEmpty shows while the list has no options, as when a search beside it finds none.

Installation

npx shadcn@latest add https://kinoui.com/r/listbox.json
Files
lib/reduce-motion.tslib/scroll.tslib/refs.tslib/field-control.tsxlib/resize.tslib/run-progress.tslib/highlight.tscomponents/kino/separator.tsxlib/popup.tslib/menu.tsxlib/pick.tscomponents/kino/listbox.tsx
Packages
@base-ui/reactclass-variance-authority

New to Kino? Installation covers what your project needs first and the @kino namespace.

API reference

Listbox

PropTypeDefaultDescription
defaultValuestring[][]The options picked at first, when you leave the state to it.
valuestring[]NoneThe picked options, by value, when you hold the state.
onValueChange(value: string[]) => voidNoneCalled when the picked options change.
multiplebooleanfalseWhether more than one option can be picked.
disabledbooleanfalseFades the whole list. It takes no focus, and its value isn’t sent with a form. A disabled Field disables it too.
namestringNoneSends each picked value with a form, under this name. A Field’s name comes first.
formstringNoneThe id of the form the values go with, when the list sits outside it.

ListboxItem

PropTypeDefaultDescription
valuestringNoneNames the option in the list’s value. Unique in the list.
textValuestringNoneWhat typing the option’s name matches, when its content holds more than its name. Its text otherwise.
disabledbooleanfalseFades the option. It can still take focus, but can’t be picked.

Data attributes

AttributeOnDescription
data-selectedthe option, [data-slot=listbox-item]Present while it is picked.
data-disabledthe option, and the box when the whole list is disabledPresent while it is disabled.

Accessibility

  • It follows the WAI-ARIA listbox pattern (opens in a new tab): the list is a listbox, each row an option with aria-selected, and a group a group named by its heading. Tab lands on one option: the picked one, else the first.
  • A <label> can’t name a listbox on its own, so in a Field the list takes aria-labelledby from its FieldLabel, and a press on the label moves focus into it. Its description and error become its aria-describedby. Outside a field, name it with aria-labelledby or aria-label.
  • While the list has no options, ListboxEmpty’s text sits in a status region that was there from the start, so it is announced, and it describes the list for anyone who reaches it.
  • Up and Down move one option and stop at the ends. Home and End go to the first and last, and typing a name moves to the next option that starts with it. Space or Enter picks.
  • With multiple, the list is aria-multiselectable: Space adds or takes an option away, Shift+Space picks from the last option picked to this one, Shift with Up or Down carries the pick along, Ctrl+Shift+Home or End picks to that end, and Ctrl+A or ⌘A picks every option.
  • A disabled option is aria-disabled and still takes focus, so it can be read. An invalid list takes aria-invalid, and keeps a dashed outline under forced colours.
  • Picked rows take the system’s highlight colours under forced colours, and the focus ring keeps an outline there.
  • When the system asks for less motion, the highlight only fades and the tick appears without growing.