Listboxes

Interactive listboxes that maintain selection state.

javascript 
import { ListBox, ListBoxItem } from '@brainandbones/skeleton';

Examples

Single Selection
  • Item 1
  • Item 2
  • Item 3

Selected: 1

Multi-Selection
  • Item A
  • Item B
  • Item C

Selected: A,B

Usage

Define a writable store to house the selection state, then add a value prop to each child. You may optionally provide an a11y-friendly label prop as well.

Single Value

Create a writable with a singular value (string, number, etc).

typescript 
const storeSingle: Writable<number> = writable(1);
html 
<ListBox selected="{storeSingle}" label="Single Selection">
    <ListBoxItem value={1}>Selection Example 1</ListBoxItem>
    <ListBoxItem value={2}>Selection Example 2</ListBoxItem>
</ListBox>

Multiple Values

Create a writable with a an array of Values.

typescript 
let storeMultiple: Writable<any[]> = writable(['A', 'B']);
html 
<ListBox selected={storeMultiple} label="Multi-Selection">
    <ListBoxItem value={'A'}>Item A</ListBoxItem>
    <ListBoxItem value={'B'}>Item B</ListBoxItem>
    <ListBoxItem value={'C'}>Item C</ListBoxItem>
</ListBox>

Properties

Listbox

Prop Type Default Values Description
selectedstringwritable(undefined)any | any[]Provide a writable store to maintain list selection.
spacestringspace-y-1classProvide classes to set vertical item spacing.
heightstring-classProvide to set scrollable listbox region height.
regionLabelstring-classProvide arbitrary classes to the label element.
regionListstring-classProvide arbitrary classes to the scrollable listbox element.

Listbox Item

These properties can be set on the parent to affect all child items.

Prop Type Default Description
accentstring!bg-primary-500Provide classes to set the selected element background.
paddingstringpx-4 py-3Provide classes to set the padding styles.
roundedstringroundedProvide classes to set the border radius styles.

Slots

Name Description
leadPositioned on the left of each row item.
trailPositioned on the right of each row item.

Accessibility

ARIA Guidelines

Listbox

Prop Type Default Description
labelstring-Define a semantic ARIA label.
labelIdstring-Set automatically based on the label text, but can be overwritten.

Listbox Item

Prop Type Default Description
idstring-Define a unique and semantic identifier for the item.

Keyboard Interactions

Keys Description
TabMoves focus to the next option.
Shift + Tab Moves focus to the previous option.
Space or EnterChanges the selection state of the focused option.