Documentation
Guides

Keyboard and type-ahead

The tree's keys follow the WAI-ARIA APG tree view, with type-ahead, rename and a keyboard drag. Every binding is an action you can rebind.

The engine handles the keys on the tree, following the WAI-ARIA Authoring Practices tree view pattern; adapters never hard-code a key. The tree is one stop in the page's tab order (the roving tab stop), and every binding can be changed with the root's keyMap.

The default keys

DEFAULT_KEY_MAP maps each action to its keys:

actionkeysdoes
"focus-next"ArrowDownthe next visible item
"focus-previous"ArrowUpthe previous visible item
"focus-first"Homethe first visible item
"focus-last"Endthe last visible item
"focus-page-down"PageDownthe item a view's worth of rows down, in a virtualized tree; otherwise the key scrolls as usual
"focus-page-up"PageUpthe item a view's worth of rows up, in a virtualized tree; otherwise the key scrolls as usual
"expand-or-focus-child"ArrowRightexpands a collapsed parent, else focuses its first child
"collapse-or-focus-parent"ArrowLeftcollapses an expanded parent, else focuses the parent
"expand-siblings"*expands the focused item's siblings
"select"Enterselects the focused item (selection())
"toggle"Spacetoggles its selection (multiple), selects it (single), or toggles its check with checkboxes() when the tree has no selection() (or with checkboxes({ space: "check" }))
"toggle-selection"Ctrl/Cmd + Spacetoggles its selection without moving
"extend-next"Shift + ArrowDownmoves down and extends the selection
"extend-previous"Shift + ArrowUpmoves up and extends the selection
"extend-to-focused"Shift + Spaceextends from the anchor to the focused item
"extend-to-first"Ctrl/Cmd + Shift + Homeextends to the first visible item
"extend-to-last"Ctrl/Cmd + Shift + Endextends to the last visible item
"select-all"Ctrl/Cmd + Aselects every visible item
"rename"F2starts renaming the focused item (rename())
"start-drag"Ctrl/Cmd + Shift + Dstarts a keyboard drag of the selection, or of the focused item

In a right-to-left tree, ArrowRight and ArrowLeft swap (Right-to-left trees).

Keyboard
Gallery

Type-ahead

Type-ahead is an opt-in feature: typeAhead(), from @fragiola/tree/type-ahead (every adapter's /type-ahead entry); a tree without it leaves typed characters alone. Installed, typing a printable character focuses the next visible item whose label starts with it, ignoring case; characters typed within typeAhead({ timeout }) milliseconds (default 500) extend one search ("re" finds "README.md"). The model answers the same question with no screen:

model.get("type-ahead-match", { text: "re", fromItemId: "app" });

Changing a binding

keyMap takes, per action, the full list of its keys, over the defaults. A key is a KeyboardEvent.key value with its modifiers ("Shift+ArrowDown", "Control+a", " " for Space); letters ignore case. An empty list turns an action off:

import { type KeyMap, Tree } from "@fragiola/tree-react";

const keyMap: Partial<KeyMap> = {
    rename: ["F2", "Enter"], // Enter renames, as in Finder
    select: [],
    "start-drag": ["Alt+m"],
};

<Tree.Root<Types> defaultTree={json} keyMap={keyMap} aria-label="Files">
    <Tree.Items<Types>>{(item) => <FileItem item={item} />}</Tree.Items>
</Tree.Root>;

The keyboard drag

"start-drag" picks up the selection (or the focused item). Then ArrowDown and ArrowUp step through the drop targets the model accepts, Enter drops (one item.move) and Escape cancels. The live region tells a screen reader where the drop would go, in your words: Drag and drop.

Keys of your own

The root's onKeyDown (@keydown in Vue, (keydown) in Angular) runs after the engine's handler; a key the engine used has its default prevented (event.defaultPrevented). Add a shortcut the tree does not use:

const [model] = useState(() => createTreeModel<Types>(json));

<Tree.Root<Types>
    model={model}
    aria-label="Files"
    onKeyDown={(event) => {
        if (event.key === "Delete" && !event.defaultPrevented) {
            model.run("item.remove", { itemIds: [...model.state.selectedItemIds] });
        }
    }}
>
    <Tree.Items<Types>>{(item) => <FileItem item={item} />}</Tree.Items>
</Tree.Root>;

Focus

Tab moves into the tree onto its focused item (or the first selected, or the first visible item), and out of it in one step. engine.run("focus", { itemId }) moves DOM focus from code.