List

A small utility to create accessible, keyboard navigable lists like search results, selects or autocompletes.

0.3.0

Features Section titled Features

Vertical and horizontal lists
Utilities for both single and multi select lists
Supports both rtl and ltr text directions
Is unopinonated and works with any kind of lists, even virtual lists
Optionally loops, vim mode and handles tab key

Installation Section titled Installation

npm install solid-list

Usage Section titled Usage

import { createList, createMultiList } from 'solid-list'

const Search = () => {
const [results, setResults] = createSignal([])

const { active, setActive, onKeyDown } = createList({
  items: () => results().map(result => result.id), // required
  initialActive: null, // default, T | null
  orientation: 'vertical', // default, 'vertical' | 'horizontal'
  loop: true, // default
  textDirection: 'ltr', // default, 'ltr' | 'rtl'
  handleTab: false, // default = true
  vimMode: false, // default
  onActiveChange: (active) => {} // optional callback to handle changes
})

return (
  <>
    <input onKeyDown={onKeyDown} />
    <For each={result}>
      {(item, index) => (
          <a href={result.href} aria-selected={active() === index()}>{result.name}<a>
      )}
    </For>
  </>
)
}

Multi select list Section titled Multi select list

A tabbable multi select list with keyboard navigation and selection.

Rook

Chough

Raven

Jackdaw

Magpie

Jay

API reference Section titled API reference

createList

Function

Props

Property	Default	Type/Description
items	-	MaybeAccessor<T[]> The items in the list. Should be in the same order as they appear in the DOM.
initialActive	`null`	null \| T The initially active item.
orientation	`'vertical'`	MaybeAccessor<'vertical' \| 'horizontal'> The orientation of the list.
loop	`true`	MaybeAccessor<boolean> Whether the list should loop.
textDirection	`'ltr'`	MaybeAccessor<'ltr' \| 'rtl'> The text direction of the list.
handleTab	`true`	MaybeAccessor<boolean> Whether tab key presses should be handled.
vimMode	`false`	MaybeAccessor<boolean> Whether vim movement key bindings should be used additionally to arrow key navigation.
vimKeys	`{ up: 'k', down: 'j', right: 'l', left: 'h' }`	MaybeAccessor<{ down: string, left: string, right: string, up: string, }> The vim movement key bindings to use.
onActiveChange	-	(active: null \| T) => void Callback fired when the active item changes.

Returns

Property	Type/Description
active	Accessor<null \| T>
setActive	Setter<null \| T>
onKeyDown	(event: KeyboardEvent) => void

createMultiList

Function

Props

Property	Default	Type/Description
items	-	MaybeAccessor<T[]> The items in the list. Should be in the same order as they appear in the DOM.
initialCursor	`null`	null \| T The initially focused item.
initialActive	`[]`	T[] The initially active items.
initialSelected	`[]`	T[] The initially selected items.
orientation	`'vertical'`	MaybeAccessor<'vertical' \| 'horizontal'> The orientation of the list.
loop	`true`	MaybeAccessor<boolean> Whether the list should loop.
textDirection	`'ltr'`	MaybeAccessor<'ltr' \| 'rtl'> The text direction of the list.
handleTab	`true`	MaybeAccessor<boolean> Whether tab key presses should be handled.
vimMode	`false`	MaybeAccessor<boolean> Whether vim movement key bindings should be used additionally to arrow key navigation.
vimKeys	`{ up: 'k', down: 'j', right: 'l', left: 'h' }`	MaybeAccessor<{ down: string, left: string, right: string, up: string, }> The vim movement key bindings to use.
onCursorChange	-	(cursor: null \| T) => void Callback fired when the cursor changes.
onActiveChange	-	(active: T[]) => void Callback fired when the active items change.
onSelectedChange	-	(selected: T[]) => void Callback fired when the selected items change.

Returns

Property	Type/Description
cursor	Accessor<null \| T>
setCursor	Setter<null \| T>
active	Accessor<T[]>
setActive	Setter<T[]>
setCursorActive	(item: null \| T) => void
selected	Accessor<T[]>
setSelected	Setter<T[]>
toggleSelected	(item: T) => void
onKeyDown	(event: KeyboardEvent) => void

Developed and designed by Jasmin