Documentation
Getting started

Your first tree

Build a working, typed tree step by step, from the document to the recursion and the indentation, then let the model change it.

A tree is three things you write: a registry (each kind of item and the type of its data), a document (the items, in JSON), and an item component (an item template, in Angular) that renders one row and then its children. The package brings the roles, the keyboard and the focus; the selection is a feature you add in one line (Selecting).

The registry and the document

The registry types each kind of item's data; a kind with nothing to hold is undefined. The document lists the root items, then every item by its id; a parent lists its children in childItemIds.

files.ts
// in a Vue or an Angular app, from "@fragiola/tree-vue" or "@fragiola/tree-angular"
import type { TreeJson } from "@fragiola/tree-react";

export type Types = { items: { folder: undefined; file: { size: number } } };

export const json: TreeJson<Types> = {
    version: 1,
    rootItemIds: ["src", "readme"],
    items: {
        src: { kind: "folder", label: "src", childItemIds: ["app", "main"] },
        app: { kind: "file", label: "app.tsx", data: { size: 1200 } },
        main: { kind: "file", label: "main.tsx", data: { size: 300 } },
        readme: { kind: "file", label: "README.md", data: { size: 80 } },
    },
    expandedItemIds: ["src"],
};

data is checked against kind: a file without a size does not compile. The full format is on The JSON model.

The item component

You own the recursion. An item renders its row (Tree.ItemContent), then its group (Tree.Group), which calls your function with each child, so the same component renders every level:

file-item.tsx
import { type ItemOf, Tree } from "@fragiola/tree-react";
import type { Types } from "./files";

export function FileItem({ item }: { item: ItemOf<Types> }) {
    return (
        <Tree.Item item={item} className="item">
            <Tree.ItemContent className="row">
                <Tree.Toggle className="toggle">▸</Tree.Toggle>
                <span>{item.label}</span>
                {item.kind === "file" && <small>{item.data.size} B</small>}
            </Tree.ItemContent>
            <Tree.Group<Types>>{(child) => <FileItem item={child} />}</Tree.Group>
        </Tree.Item>
    );
}

item.data narrows on item.kind: inside item.kind === "file", item.data.size is a number. Tree.Toggle expands and collapses on a press; the keyboard uses the arrows on the item. Tree.Group renders nothing while its item is collapsed (in Angular, the treeGroup element stays, empty and hidden).

The root

Tree.Root is the role="tree" element. Given defaultTree, it creates the model and keeps it; Tree.Items calls your function with each root item. The accessible name is yours:

file-tree.tsx
import { Tree } from "@fragiola/tree-react";
import { FileItem } from "./file-item";
import { json, type Types } from "./files";

export function FileTree() {
    return (
        <Tree.Root<Types> defaultTree={json} aria-label="Project files" className="tree">
            <Tree.Items<Types>>{(item) => <FileItem item={item} />}</Tree.Items>
        </Tree.Root>
    );
}

Tree.Items and Tree.Group hand items to a function, and a function cannot infer the registry through context: give them the type argument (<Tree.Items<Types>>).

The styles

Nothing is styled. Indent each row by its depth, which every part carries as --tree-depth (0 for a root item), and style the state through the data-* attributes:

file-tree.css
.row {
    display: flex;
    align-items: center;
    gap: 0.25rem;
    padding-inline-start: calc(var(--tree-depth) * 1rem + 0.25rem);
}
.toggle[data-leaf] {
    visibility: hidden; /* a leaf keeps the room, so labels line up */
}
.toggle[data-expanded] {
    rotate: 90deg;
}
.item:focus-visible > .row {
    outline: 2px solid #2563eb;
}

The item is the element that takes DOM focus, so its focus ring is drawn on its row. See Styling the depth and State attributes.

Hello tree
Gallery

Selecting

The tree above focuses and expands; it selects nothing. Selection is a feature: give the root selection() in its features (and the type argument for them), and a click or Enter selects, with aria-selected and data-selected to style (Selection).

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

const features = [selection()] as const;

<Tree.Root<Types, typeof features> defaultTree={json} features={features} aria-label="Project files" className="tree">
.row[data-selected] {
    background: #dbeafe;
}

Changing the tree

Every change is a command on the model. Create the model yourself to reach it from outside the tree, and pass it as model:

import { createTreeModel, Tree } from "@fragiola/tree-react";
import { useState } from "react";
import { FileItem } from "./file-item";
import { json, type Types } from "./files";

export function FileTree() {
    const [model] = useState(() => createTreeModel<Types>(json));
    const addFile = () =>
        model.run("item.add", {
            item: { kind: "file", label: "notes.md", data: { size: 0 } },
            to: { parentItemId: "src" },
        });
    return (
        <>
            <button type="button" onClick={addFile}>
                New file in src
            </button>
            <Tree.Root<Types> model={model} aria-label="Project files">
                <Tree.Items<Types>>{(item) => <FileItem item={item} />}</Tree.Items>
            </Tree.Root>
        </>
    );
}

model.run returns { ok: true, value } or { ok: false, error }: it never throws on bad input. Every command is listed on Commands.

Next