@carissa-io/components-listbox

The option list of a select, combobox or menu, with the keyboard behaviour they share. No popup logic and no focus of its own: the keyboard stays on the trigger or input that owns it. React component, SCSS-themed.

npm i @carissa-io/components-listbox

Use

import { useId, useState } from 'react'
import { Listbox, getOptionId, useListboxKeyDown } from '@carissa-io/components-listbox'

const options = [
    { value: 'free', label: 'Free' },
    { value: 'pro', label: 'Pro' },
    { value: 'team', label: 'Team', disabled: true },
]

function Example() {
    const id = useId()
    const [open, setOpen] = useState(false)
    const [value, setValue] = useState()
    const [active, setActive] = useState()

    const select = (next) => {
        setValue(next)
        setOpen(false)
    }
    const onKeyDown = useListboxKeyDown({
        options,
        value,
        active,
        onActiveChange: setActive,
        onSelect: select,
        isOpen: open,
        open: () => setOpen(true),
        close: () => setOpen(false),
    })
    const activeIndex = options.findIndex((option) => option.value === active)

    return (
        <>
            <button
                type="button"
                role="combobox"
                aria-haspopup="listbox"
                aria-expanded={open}
                aria-controls={id}
                aria-activedescendant={open && activeIndex >= 0 ? getOptionId(id, activeIndex) : undefined}
                onKeyDown={onKeyDown}
                onClick={() => setOpen(!open)}
            >
                {value ?? 'Choose'}
            </button>
            {open ? (
                <Listbox
                    id={id}
                    options={options}
                    value={value}
                    active={active}
                    onActiveChange={setActive}
                    onSelect={select}
                    empty="No options"
                />
            ) : null}
        </>
    )
}

Listbox

| Prop | | |---|---| | options | [{ value, label, disabled }]; label can be any node | | value | the selected option's value (aria-selected) | | active | the active (highlighted) option's value, controlled by the parent | | onActiveChange(value) | pointer move over an enabled option | | onSelect(value, option) | click on an enabled option | | id | the <ul> id (generated with useId when omitted); option ids derive from it | | empty | node shown (as li.c-listbox__empty) when there are no options; nothing is rendered if it is omitted | | className, … | className and any other prop go to the <ul role="listbox"> |

• Ids: option i has the id getOptionId(listboxId, i) (<listbox id>-option-<i>), stable across renders. Point the trigger's aria-activedescendant at the active one.
• Focus: a press on an option calls preventDefault() on pointerdown and mousedown, so the trigger or input keeps the focus. The active option is scrolled into view (scrollIntoView({ block: 'nearest' })) when it changes.
• Classes: c-listbox, c-listbox__option (modifiers --active, --selected, --disabled), c-listbox__empty.

Keyboard

listboxKeyDown(event, config) is the pure helper and useListboxKeyDown(config) returns a stable onKeyDown that owns its typeahead buffer. Both return true when they handled the key (and called event.preventDefault()).

| Config | | |---|---| | options, value, active | the same values the list gets (value is where an ArrowDown/ArrowUp on a closed list starts) | | onActiveChange(value), onSelect(value, option) | as above | | isOpen (true), open(), close() | the popup state; the default isOpen: true suits an always-visible list | | typeahead | true (a shared buffer), false, or a createTypeahead() instance (the hook creates its own) | | allow_space_select (true) | Space selects; pass false for a text input, where Space types a space | | open_on_enter (true) | Enter opens a closed list; pass false for a text input | | home_end (true) | Home/End move the active option; pass false for a text input, where they move the caret |

• Open: ArrowDown/ArrowUp move to the next/previous enabled option (no wrap; with nothing active, the first/last), Home/End the first/last enabled one, Enter and Space select the active option (with nothing active they do nothing), Escape closes. Tab closes but is not handled, so focus moves on. Disabled options are always skipped.
• Closed: ArrowDown, ArrowUp, Enter and Space call open(); the arrows activate the selected option (or the first/last), the others the selected or first one.
• Typeahead: a printable character activates the first enabled option whose text starts with what was typed in the last ~700 ms (the label when it is a string, else the value as a string). On a closed list it opens it. While a word is being typed, Space continues it instead of selecting. The buffer stores the time of the last key: there are no timers to clean up. createTypeahead({ timeout, now }) returns { match(options, char), isActive(), reset() }.
• Keys with Ctrl, Meta or Alt are never handled.

Style

@use '@carissa-io/components-listbox/scss' with (
    $c-listbox-option-active-background: #f5f5f5,
    $c-listbox-option-selected-marker-width: 2px,
    $c-listbox-max-height: 15rem
);

All variables are in scss/_variables.scss: font, max height (the list scrolls past it), option color, background, padding, minimum height and separator, the active, selected (font weight, color and a marker bar on the inline-start side) and disabled states, the empty state, and the transition.