Documentation
Guides

Selection

Choose a selection mode, select with the pointer, the keyboard or commands, and read the selection back to act on it.

The selection is a feature (Features): a tree without it focuses and expands, and selects nothing. With it, the selection is model state: state.selectedItemIds, in the order the items were selected. The package selects on a press and on the keys of the WAI-ARIA tree view, and sets aria-selected and data-selected; what a selection means (open a file, delete, move) is yours.

Installing it

Install selection(options?) in the model's features. Its mode is the selection mode a document without one gets: "single" (the default), "multiple" or "none".

import { createTreeModel } from "@fragiola/tree-react";
import { selection } from "@fragiola/tree-react/selection";

const features = [selection({ mode: "multiple" })] as const;
const model = createTreeModel<Types, typeof features>(json, { features });

Choosing a mode

The document's settings.selectionMode (with the feature) wins over the option:

const json: TreeJson<Types> = {
    version: 1,
    settings: { selectionMode: "multiple" },
    rootItemIds: ["engineering", "design"],
    items: {
        /* … */
    },
};

Change it later with a command; a narrower mode trims the selection:

model.run("tree.configure", { settings: { selectionMode: "single" } });

With "none", the items carry no aria-selected and every selection command is refused. A disabled item is never selected.

Pointer and keyboard

inputdoes
a press on a rowselects it alone
Shift + pressselects the visible items from the anchor to it (multiple)
Ctrl/Cmd + pressadds it to the selection or removes it (multiple)
Enterselects the focused item alone
Spacetoggles the focused item's selection (multiple), or selects it (single)
Ctrl/Cmd + Spacetoggles the focused item's selection without moving
Shift + Down / Upmoves and extends the selection
Shift + Spaceextends from the anchor to the focused item
Ctrl/Cmd + Shift + Home / Endextends to the first / last visible item
Ctrl/Cmd + Aselects every visible item (multiple)

Moving the focus with the arrows does not select. Pass expandOnClick to the root to make a press on a parent's row also expand or collapse it, as in a file explorer; the toggle always does. Every key can be rebound (Keyboard and type-ahead).

Multiple selection
Gallery

Selecting from code

model.run("item.select", { itemId: "maria" }); // alone, and the anchor
model.run("item.select", { itemId: "lee", mode: "toggle" }); // add or remove
model.run("item.select", { itemId: "kim", mode: "extend" }); // from the anchor to kim
model.run("tree.select", { itemIds: ["maria", "lee"] }); // exactly these
model.run("tree.select-all", {}); // every visible item (multiple)
model.run("tree.clear-selection", {});

Reading the selection

model.get("selected-items") returns the selected items themselves. In a component, useTreeState re-renders only when the selection changes (in Vue, a read-only ref that changes only then; in Angular, injectTreeState, a signal):

import { useTree, useTreeState } from "@fragiola/tree-react";
import { features, type Types } from "./tree";

function SelectionBar() {
    const { model } = useTree<Types, typeof features>();
    const selected = useTreeState<Types, readonly string[], typeof features>(
        (state) => state.selectedItemIds,
    );
    if (selected.length === 0) return null;
    return (
        <div role="toolbar" aria-label="Selection">
            <span>{selected.length} selected</span>
            <button type="button" onClick={() => model.run("item.remove", { itemIds: [...selected] })}>
                Delete
            </button>
            <button type="button" onClick={() => model.run("tree.clear-selection", {})}>
                Clear
            </button>
        </div>
    );
}

Render it inside Tree.Root (a child of the root renders next to the items), or outside with a tree ref. To own the selection in your app's state instead, see Controlled state.

Styling it

.row[data-selected] {
    background: #dbeafe;
}

Each row carries its own item's data-selected, so a selected parent does not color its children.