Typed data
Declare each kind of item and the type of its data once; the document, the commands and every item you render are then checked against it.
An app declares its tree's registry: each item kind, and the type of that kind's data.
Everything typed by the model follows from it: the document, the payloads of item.add and
item.set-data, and the items the primitives hand you.
type Types = {
items: {
folder: undefined; // a folder holds no data
file: { size: number; modified: string };
link: { url: string };
};
};Items narrow on their kind
ItemOf<Types> is a union discriminated by kind, so data narrows:
function Meta({ item }: { item: ItemOf<Types> }) {
switch (item.kind) {
case "file":
return <small>{item.data.size} B</small>; // { size: number; modified: string }
case "link":
return <small>{new URL(item.data.url).host}</small>;
case "folder":
return null; // item.data is undefined
}
}KindOf<Types> is the union of kinds and DataOf<Types, "file"> one kind's data type. With no
registry, AnyTypes accepts any kind with unknown data.
The document and the commands
TreeJson<Types> checks each item's data against its kind, and requires it when the kind's
data cannot be undefined:
const json: TreeJson<Types> = {
version: 1,
rootItemIds: ["readme"],
items: {
readme: { kind: "file", label: "README.md", data: { size: 80, modified: "2026-11-01" } },
},
};
model.run("item.add", {
item: { kind: "link", label: "Docs", data: { url: "https://fragiola.com/tree" } },
to: { parentItemId: null },
});
model.run("item.set-data", { itemId: "readme", data: { size: 120, modified: "2026-11-16" } });A file without size, or a link with a size, does not compile. TreeItemJson<Types> is one
item in JSON (as loadChildren returns them).
Passing the registry along
createTreeModel<Types>(json) types the model, and <Tree.Root<Types>> the root. A part that
hands you items through a function (Tree.Items, Tree.Group) cannot infer the registry through
React context: pass it as their type argument. The hooks take it the same way:
<Tree.Items<Types>>{(item) => <Node item={item} />}</Tree.Items>
<Tree.Group<Types>>{(child) => <Node item={child} />}</Tree.Group>
const { model } = useTree<Types>();
const tree = useTreeRef<Types>();Checking data at run time
Types check your code; a document from a server or an assistant is checked at run time. Give the
model a JSON Schema per kind, and the document, item.add, item.set-data and
item.set-children validate data against it:
const model = createTreeModel<Types>(json, {
dataSchemas: {
file: {
type: "object",
properties: { size: { type: "number" }, modified: { type: "string" } },
required: ["size", "modified"],
},
},
});An invalid document throws a TreeValidationError listing every problem with its JSON path; an
invalid payload is refused with invalid_payload. The FromSchema type derives a TypeScript type
from a schema written as const, if you would rather write the schema first.
Parts and paths
Every element carries data-tree-part, and every item data-tree-path, its position from the root, so tests and tooling never depend on class names.
Glossary
The words these pages, the API and the examples use, each with one meaning - item, leaf, expanded, selected, checked, focused, drop target and more.