Features
A minimal core and opt-in features - selection, checkboxes, rename, async children, type-ahead, virtualization, drags - so a tree ships only what it installs.
The tree is a minimal core and opt-in features. With no feature, a tree renders, expands and collapses, and moves one roving tab stop with the WAI-ARIA keys: it is a complete, accessible tree. A feature adds one capability, its state, commands, keys and ARIA, and comes from its own entry: an app that never imports it does not ship it.
| feature | entry | adds |
|---|---|---|
selection(options?) | @fragiola/tree-react/selection | the selected items, the selection mode (single by default, multiple, none), item.select and the other selection commands, the keys and clicks that select, aria-selected, data-selected, aria-multiselectable, and the selectedItemIds prop |
checkboxes(options?) | @fragiola/tree-react/checkboxes | tri-state checks (checkedItemIds, cascade by default or independent), item.check, item.toggle-check, aria-checked, data-checked, data-indeterminate, Space to toggle the check (space), and the checkedItemIds prop; the check control is yours (Checkboxes) |
rename(options?) | @fragiola/tree-react/rename | the renaming item, the renamable flag and default, item.start-rename (F2), item.rename, item.cancel-rename, the engine's commit-rename and cancel-rename, data-renaming, and useTreeItemRename for your own input (Rename) |
asyncChildren() | @fragiola/tree-react/async-children | parents whose children come from your loadChildren (childrenStatus), their commands, the engine's load-children, aria-busy, data-loading, data-load-error, and the loadChildren prop (Async loading) |
typeAhead(options?) | @fragiola/tree-react/type-ahead | typed characters focus the next item whose label starts with them (timeout), and model.get("type-ahead-match") (Keyboard and type-ahead) |
virtualization(options?) | @fragiola/tree-react/virtualization | a window of the visible items in view, rendered by VirtualItems, for trees of hundreds of thousands of rows (Virtualization) |
dragAndDrop(options?) | @fragiola/tree-react/drag-and-drop | the Pointer Events drag and the keyboard drag of the tree's items (one item.move per drop), auto-expand and auto-scroll, DropIndicator, data-dragging, data-drop-target, data-drop-position, and the drag keys (drop-target, start-keyboard-drag, …) (Drag and drop) |
dragGroup({ name, transfer? }) | @fragiola/tree-react/drag-group | drags between the trees of a group, a transfer between two models, data-dragging-from-other-tree; needs dragAndDrop() (Between trees) |
foreignDrop({ accept?, onDrop }) | @fragiola/tree-react/foreign-drop | files, links and text dropped from outside, with the same target and DropIndicator, with or without dragAndDrop() (Foreign content) |
dropOutside({ onDrop }) | @fragiola/tree-react/drop-outside | rows dropped on your own targets outside every tree, drop-outside-element; needs dragAndDrop() (Dropping outside) |
item.move and the movable and droppable flags stay in the core: a tree without drag and drop
still moves items by command. Each framework's package has the same entries (@fragiola/tree-vue/selection,
@fragiola/tree-angular/virtualization, …), and the core's are @fragiola/tree/<feature>.
Installing
The model takes its features once, when it is created, and keeps them: a later change of a
root's features prop is ignored, with a warning.
import { createTreeModel, Tree } from "@fragiola/tree-react";
import { selection } from "@fragiola/tree-react/selection";
const features = [selection({ mode: "multiple" })] as const;
export function Files() {
const [model] = useState(() => createTreeModel<Types, typeof features>(json, { features }));
const count = useTreeState((state) => state.selectedItemIds.length, { model });
return (
<Tree.Root model={model} aria-label="Files">
<Tree.Items<Types>>{(item) => <FileItem item={item} />}</Tree.Items>
</Tree.Root>
);
}
// or a root that creates its own model
<Tree.Root<Types, typeof features> defaultTree={json} features={features} aria-label="Files">Typed by the features
The features type the model, the engine and everything around them. model.run("item.select", …)
compiles only with selection(); model.state.selectedItemIds and engine.get("virtual-window")
exist only with their feature; a root's selectedItemIds prop compiles only when its model has
the selection. At runtime, a command of a feature that is not installed returns not_found, its
get key reads undefined and its is key answers false: nothing throws.
TypeScript infers the features from createTreeModel(json, { features }) when it infers the
registry too. When you give the registry (createTreeModel<Types>(…)), give the features as
well (createTreeModel<Types, typeof features>(…), with const features = [...] as const), and
in the same way to Tree.Root, useTree, useTreeRef, useTreeState and typedTree. Given a
model, useTreeState infers them.
Documents
A document is the same JSON with or without features (The JSON model), and
a field belongs to its feature: selectedItemIds, selectionAnchorItemId and
settings.selectionMode load only into a model with selection(); checkedItemIds and
settings.checkMode with checkboxes(); renamingItemId, settings.renamable and an item's
renamable with rename(); an item's childrenStatus with asyncChildren(). Elsewhere they
are a validation issue (requires the selection feature), never dropped silently, and
model.get("tree-json") writes only the installed features' fields. Check a saved document
against the model's features with validateTree(json, { features }).
What stays outside
As everywhere in the tree: no styles, no rendered menus, no text. A feature gives behaviour, state,
ARIA and data-*; what its state looks like is your CSS ([data-selected]). The bundle of each
package is checked by pnpm build: no main entry contains a feature's code.
Model and engine
The model holds what is true with no screen; the engine is one tree on screen. Here is which state lives where, and why it matters.
Composition
You own the recursion. The primitives hand you items through children functions, and your item component decides what each row and group renders.