Documentation
Getting started

Installation

Add the tree view to a React 19, Vue 3.5 or Angular 22 app with one package, the primitives for your framework, which bring the whole core.

Not on npm yet

The packages are not published on npm yet: these pages describe the upcoming first release, and the commands below will work once it is out. Until then, the repository (github.com/fragiola/tree) builds them from source.

A React app installs one package, @fragiola/tree-react: the Tree.* primitives, the hooks and the whole framework-free core (@fragiola/tree), re-exported.

pnpm add @fragiola/tree-react

Requirements

requirementwhy
react and react-dom ^19 (React)peer dependencies of @fragiola/tree-react. The primitives use React 19 features: ref as a plain prop and ref cleanup functions.
vue ^3.5 (Vue)the peer dependency of @fragiola/tree-vue. The primitives are render functions: no compiler plugin is needed beyond your app's own.
@angular/core ^22 (Angular)the peer dependency of @fragiola/tree-angular. Standalone directives built on signals: no NgModule, and no zone.js (zoneless is Angular's default).
A browser DOMthe engine focuses elements, listens to Pointer Events and measures rows during a drag. The model runs in plain Node (tests, server-side JSON handling), but a tree is interactive only on the client.
ES modulesevery package is ESM only ("type": "module"; the Angular package in the Angular Package Format).

@fragiola/tree has zero runtime dependencies, and each adapter (@fragiola/tree-react, @fragiola/tree-vue, @fragiola/tree-angular) depends only on the core, at the exact same version, and on its framework.

Every package ships its types and is best used with TypeScript in strict mode: the document, the command payloads and each item's data are typed by your registry (Typed data). Plain JavaScript works too: the model validates every command's payload at run time either way.

What to import from where

Everything comes from @fragiola/tree-react:

import {
    // the primitives (one namespace) and the hooks
    Tree,
    useTree,
    useTreeState,
    // the core: the model, its types and helpers
    createTreeModel,
    type ItemOf,
    type TreeJson,
} from "@fragiola/tree-react";

The React package re-exports the whole core (createTreeModel, TreeModel, TreeJson, ItemOf, Middleware, veto, createTreeEngine, DEFAULT_KEY_MAP, …), so the pages on the core API apply as they are: in a React app, import those names from @fragiola/tree-react too.

Features

The package is a minimal tree and opt-in features, each from its own entry of the same package: selection() from @fragiola/tree-react/selection, and virtualization() (with VirtualItems) from @fragiola/tree-react/virtualization (@fragiola/tree-vue/…, @fragiola/tree-angular/…). A feature you do not import is not in your bundle; one you import, you install in the model's features (Features).

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

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

Without a framework

The core is published on its own as @fragiola/tree, for code that renders nothing: handling tree JSON on a server, a script or a test that runs no framework, or an adapter for another framework.

pnpm add @fragiola/tree
import { createTreeModel, type TreeJson } from "@fragiola/tree";

An app never needs it: it comes with its adapter.

Server rendering

The primitives render on the server: Tree.Root outputs the tree's markup with its roles and state, and creates its engine (focus, keys, drags, the loader) only once it is mounted in the browser. A server render neither subscribes to the model nor changes it.

In Next.js, the file that renders the tree is a client component:

app/files/file-tree.tsx
"use client";

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

type Types = { items: { folder: undefined; file: undefined } };

export function FileTree({ json }: { json: TreeJson<Types> }) {
    return (
        <Tree.Root<Types> defaultTree={json} aria-label="Files">
            <Tree.Items<Types>>
                {(item) => (
                    <Tree.Item item={item}>
                        <Tree.ItemContent>{item.label}</Tree.ItemContent>
                    </Tree.Item>
                )}
            </Tree.Items>
        </Tree.Root>
    );
}

Next

Your first tree builds a working, typed tree step by step.