Behaviors

Where behavior lives#

Koala components get dialogs, menus, popovers and tabs from Radix primitives. The patterns Radix leaves open, an input that drives a list, a group with one tab stop, a value a parent may own, live in a few hooks in lib/. Combobox, Command, Select Search, Multi Select, List and the editor menus all run on them, so every list answers the same keys in the same way.

Building a component Koala does not ship? Reach for a Radix primitive first, then for these hooks, and keep only the look in your own tv recipe. Never write keyboard or ARIA logic inside the component.

A value the parent may own#

Every Koala component takes value or defaultValue. One hook decides which applies, and calls onValueChange only when the value really changes.

import { useControllableState } from "@/lib/controllable"

export function Rating({ value, defaultValue = 0, onValueChange }) {
  const [rating, setRating] = useControllableState({
    value,
    defaultValue,
    onChange: onValueChange,
  })
  // setRating(3), or setRating((n) => n + 1)
}

An input that drives a list#

Focus stays in the input while the highlight moves through the rows. The arrows wrap, Home and End jump to the ends, PageUp and PageDown move ten rows, Cmd+arrow jumps on macOS and Enter picks the lit row. Nothing moves while an input method is composing a word, and a finger sliding over the list on touch never lights a row.

import { useActiveDescendant } from "@/lib/listbox"

const listRef = React.useRef(null)
const inputRef = React.useRef(null)
const list = useActiveDescendant({ listRef, inputRef, item: '[role="option"]' })

<input ref={inputRef} role="combobox" aria-controls="envs" onKeyDown={list.handleKeyDown} />
<div ref={listRef} id="envs" role="listbox">
  {environments.map((env) => (
    <div key={env.id} id={env.id} role="option" onPointerMove={list.highlightOnPointer} onClick={() => pick(env)}>
      {env.name}
    </div>
  ))}
</div>

One tab stop for a group#

Tab enters the group on the selected item and leaves it in one press; the arrows move inside. When the focused item is removed, focus moves to the one now in its place.

import { useRovingFocus } from "@/lib/roving-focus"

const roving = useRovingFocus({ item: "[data-file]:not([aria-disabled=true])" })

<ul ref={roving.ref} onFocus={roving.onFocus} onKeyDown={roving.onKeyDown}>
  {files.map((file) => <li key={file.id} data-file tabIndex={-1}>{file.name}</li>)}
</ul>

API reference#