Overview

Trees uses one path-first model. The model works the same across React, vanilla, and SSR hydration. Selection, focus, search, rename, drag and drop, Git status, and row annotations all use canonical paths.

These docs are guide-first. First, select your runtime. Next, shape the tree data before it reaches the UI. Then add search, item actions, styling, icons, row signals, or SSR when you need them.

Guides

@pierre/trees gives you one path-first model and two primary runtime entries: a thin React layer in @pierre/trees/react and the vanilla class in @pierre/trees.

Choose your integration

1. Path-first identity

Use canonical path strings as the public identity for each item in the tree. For example, src/components/Button.tsx is more than a label on screen. It is the value that you read from selection state. It is the path that you focus in code. It is also the target that you rename or move later.

To learn the shared terms behind this rule, read Shared concepts.

2. React vs Vanilla JS

Use the React entry point when your UI is already in React. For more information, read the getting started with React guide.

Use the vanilla class in two cases. Use it when your app is not React-based. Also use it when another framework must own the lifecycle around an imperative model. For more information, read getting started with vanilla JS.

3. Understand tree-shape

Both runtimes use the same tree data. Small examples can start with raw paths. But real application trees must move to prepared input. This step prevents the client from doing the shaping work on every load. Read Shape tree data for fast rendering after your runtime quickstart. This step applies to both React and vanilla JS.

Get started with React

Use the React entry point when your UI is already in React. The hook creates one stable tree model. The component mounts that model into the host element.

Install @pierre/trees

Use the package root for the vanilla runtime. Use the /react entry point for the React wrapper.

Create the model with useFileTree(...)

useFileTree(...) from @pierre/trees/react creates the model one time for the component lifetime. Later option changes do not update the model. Update the model through methods when the tree data or runtime behavior changes after mount. The methods include resetPaths(...), setComposition(...), setGitStatus(...), and setIcons(...).

For small trees, pass raw paths. For scalable trees, use preparedInput. Create preparedInput on the server or another non-UI boundary.

Read Shape tree data for fast rendering after this quickstart if you must still decide how to shape that input.

Render with <FileTree model={model} />

<FileTree /> is a thin React wrapper over the model. It mounts the tree into the host element. It forwards normal host props such as className and style. It also hydrates existing server output when you pass preloadedData later.

Keep the mental model simple. The model owns the tree state. The React component renders it.

Read and update tree state through the model

React code reads snapshots from the model through selector hooks. React code writes back through model methods.

Use useFileTreeSelector(model, selector, equality?) when sibling UI needs a custom derived snapshot. This hook does not rerender on unrelated tree changes. For the shared interaction terms, read Navigate selection, focus, and search and React API.

Use simple paths input only when the tree is small

Raw paths is the low-ceremony path for demos, tests, and very small static trees. It is not the scalable default. Move the shape or sort work out of the UI when the tree becomes expensive on the client.

Move to prepared input before the tree gets expensive

Use this recommended scale path:

1. Load canonical paths on the server or another non-UI boundary.
2. Prepare the tree input one time.
3. Pass preparedInput into useFileTree(...).

Use preparePresortedFileTreeInput(...) when the server already knows the final order. It is the highest-performance prepared-input variant. The client can skip both the shaping work and the extra sorting work.

Add SSR later when first paint matters

Hydration builds on top of the same model-first React story. The client still calls useFileTree(...). The React wrapper still renders the same model. The one difference is that the tree starts from preloaded server output.

Continue with SSR and SSR API when you need that flow.

Get started with vanilla

Use the vanilla runtime in two cases. Use it when your app is not React-based. Also use it when another framework must own the lifecycle around an imperative tree model. new FileTree(...) creates the model. render(...) or hydrate(...) attaches the model to the DOM.

Install @pierre/trees

Create the model with new FileTree(...)

The class instance is the runtime entry point and the state surface. For small trees, pass raw paths. For scalable trees, use preparedInput. Create preparedInput outside the UI.

Render into a host element

render({ fileTreeContainer }) mounts the model into an existing host element. Use render({ containerWrapper }) instead when the runtime must create the host for you.

Keep the boundary clear. The model owns the tree state. The mounted host only renders that state. Do not read the DOM to find the selected item or the current focus. Read and update those values through the model.

Read and update tree state through the model

The instance gives you direct read methods, item handles, and imperative controls.

Call explicit model methods when the surrounding data changes. The methods include resetPaths(...), setComposition(...), setGitStatus(...), and setIcons(...). Do not build the model again in place.

Use simple paths input only when the tree is small

Raw paths is the low-ceremony path for demos, tests, and small static trees. It is not the recommended setup for repo-scale or workspace-scale trees.

Move to prepared input before the tree gets expensive

Use this recommended scale path:

1. Load canonical paths outside the UI.
2. Prepare the tree input one time.
3. Construct new FileTree({ preparedInput, ... }).

Use preparePresortedFileTreeInput(...) when the server or indexer already knows the final order. It is the better fit because the client can skip the extra sorting work.

Add SSR later when server rendering matters

Hydration builds on top of the same class-first runtime. The client still creates new FileTree(...). But the client does not render fresh markup. Instead, it attaches that model to server-rendered tree output with hydrate({ fileTreeContainer }).

Continue with SSR and SSR API when you need that flow.

Advanced note: wrapping the vanilla model in another framework

Keep the same ownership boundary when you wrap the vanilla model in another framework:

• create and own the FileTree instance from that framework's lifecycle
• mount or unmount around the instance
• keep all tree reads and writes on the model

This approach keeps React as the only first-class wrapper surface. It does not change how the model works.

Shape tree data for fast rendering

Shape the tree before it reaches the UI when the dataset is large. Then this out-of-UI preparation is worth the effort. Trees treats prepared input as a first-class public concept. It is not an internal optimization trick.

Start with server-prepared input for scalable trees

prepareFileTreeInput(...) lets the client skip repeated tree-shape work. Do this preparation on the server, a loader, or another non-UI boundary. That boundary already has the full path list.

The client still uses the same path-first model. Only the expensive preparation step moves earlier.

Pass preparedInput into the runtime

Both primary runtimes use the same prepared payload shape.

Use simple paths input only for small trees

Raw paths is still the right choice for small demos, tests, and very small static trees.

This is the easy start path, not the scale-oriented default. Move the preparation work out of the client when the tree grows.

Presorted input is the highest-performance prepared-input path

Use preparePresortedFileTreeInput(...) when your server or indexer already knows the final order. It skips the tree-shape work. It also skips the extra sort work that a normal prepared-input pass applies.

Use this path when the backend, build step, or cached index already owns the sort order. Do not write the default order again in the client only to reach the presorted path.

Prepare on the server, render on the client

Use this simple split:

1. Load canonical paths outside the UI.
2. Prepare the input one time.
3. Pass preparedInput into React, vanilla, or SSR hydration.

This split reduces client CPU work. It makes the startup cost more predictable. It also lets the same prepared payload feed every runtime.

Keep client-side sorting and preparation secondary

Sometimes the data exists only in the browser. Sometimes custom order must run there. Trees supports both cases, but they are the exception path. Start with prepared input when the app can move the work out of the UI. Use client-side shaping only as a fallback.

To learn the shared contract behind these inputs, read Shared concepts. For the scale-oriented version of this guidance, continue with Handle large trees efficiently.

Navigate selection, focus, and search

The tree model tracks three user-facing states: selection, focus, and the visible row set. Search builds on the same model. It does not add a separate identity system.

Start with the interaction state model

Selection, focus, keyboard movement, and search all use canonical paths. The visible tree can change when a branch collapses or when search removes rows. Your app still uses the same path values.

For this reason, the public APIs return path-based results. Selected paths are a readonly string[]. Focused items are path strings. Search matches are path strings.

Selection and focus are related but different

Focus tells you where keyboard actions land. Selection tells you which rows the app treats as chosen. The two often move together. But they are not the same.

Read the selected paths when you need the multi-select state in surrounding UI. Read the focused path or item handle when you need to know where a rename, keyboard action, or command lands next.

Keyboard navigation follows the visible tree

Keyboard movement works on the visible, expanded tree. Expand or collapse a branch to change which row receives focus next. Search changes the same visible tree. So search also changes where keyboard movement lands.

For this reason, Trees exposes focus and selection through the model. It does not use DOM order or row indexes.

Add search on top of that same state

Search matches the same path-first tree data. It changes what stays visible. But it does not add a second identity model. Selection and focus still use paths. The visible window changes around the current query.

Guide default: hide-non-matches

Start with hide-non-matches. Change it only when the product needs unrelated branches on screen. This mode fits the common "find the thing I want" workflow. It keeps the visible tree close to the current search intent.

Trees also supports collapse-non-matches and expand-matches. Use those modes when the surrounding UI needs more context. But keep hide-non-matches as the default mental model. The shared meaning of all three modes is in Shared concepts.

React integration notes

React reads from the model through selector hooks. React writes back through model methods.

Use useFileTreeSelector(...) when sibling UI needs a custom derived snapshot.

Vanilla integration notes

Vanilla code connects the same behavior to the class instance.

The DOM host is not the source of truth. The model is the source of truth.

What to read next

• For runtime-specific lookup, read React API or Vanilla API.
• For shared search-mode semantics, read Shared concepts.
• For row-level editing workflows that build on this focus model, continue with Rename, drag, and trigger item actions.

Rename, drag, and trigger item actions

This guide covers the main row-level editing workflows. Rename comes first. Drag and drop comes second. Optional command surfaces, such as context menus, come last. Every callback stays path-first.

Start with direct row actions

The core row workflows are:

1. rename in place
2. drag and drop
3. optional context-menu commands

Learn these flows before you use a generic mutation inventory. Users care about three things. They care about which path moved. They care about which path changed its name. They care about which row stays focused next.

Rename items in place

Enable renaming when users must rename rows inline. The common policy hooks are:

• canRename(item) to block protected files or folders
• onRename(event) to respond to the final path change
• onError(error) to show invalid rename attempts

The rename event reports three values. It reports the source path. It reports the destination path. It reports whether the item was a folder.

Move items with drag and drop

Enable dragAndDrop when users must move files or folders directly in the tree. The practical hooks are:

• canDrag(paths) to lock specific paths
• canDrop(event) to reject invalid destinations
• onDropComplete(event) for persistence or adjacent UI updates
• onDropError(error, event) for visible failures

Drop callbacks report the dragged paths and the resolved target shape. They do not ask you to find the DOM rows yourself.

Combine rename and drag safely

A common editable project tree enables both renaming and dragAndDrop. Then it adds policy guards for protected paths.

Typical rules include:

• block rename for root config files such as package.json
• reject drops into generated directories such as dist/
• show rename and drop failures outside the tree; do not fail silently

Add a context menu as an optional command surface

Context menus are secondary command surfaces over the same model. Keep rename and drag available. Do not require the menu.

In React, the wrapper can render the menu content for you:

In vanilla, use composition.contextMenu.render to supply the menu element directly from the runtime config.

Lock window scroll while a menu is open

The tree blocks scrolling inside its own pane while a context menu is open. This keeps the menu on its row. But the tree cannot reach the scroll containers that your page owns. A portaled menu attaches to a point in the viewport. So the menu disconnects from its row when the window scrolls. Lock the window scroll for the menu's lifetime. Release the lock when the menu closes:

Some menu primitives have a modal mode. Radix and libraries built on it, such as shadcn/ui, lock scroll for you when the menu is modal. Apply the manual lock for a non-modal menu. The docs demos on this site apply this manual lock.

Keep keyboard and focus behavior predictable

The focused row is the anchor for rename and keyboard commands. Restore focus in a predictable way when a menu opens and closes. Keyboard users must reach the main actions without pointer-only gestures.

The tree owns the interaction surface. Your app owns persistence.

Trees emits path-based rename and drop events. Your app decides whether to save those changes. It can save them to a server, local state, or another boundary. Keep this separation clear.

To learn the shared terms behind those events, read Shared concepts. For runtime lookup, read React API or Vanilla API.

Style and theme the tree

Start with the host element. Then move inward. Host styles control the outer panel. CSS variables control most of the tree appearance. themeToTreeStyles(...) maps an editor-like theme into the same variable system. unsafeCSS is the escape hatch when the supported surfaces cannot reach a narrow case.

Start with host styling

The host element is the outer panel boundary. Use it for width, height, borders, radius, background, and layout placement.

In React, pass normal host props to <FileTree model={...} />.

In vanilla, style the mounted host element that you already own. After mount, getFileTreeContainer() returns that element when runtime code must update it.

Use CSS variables for most visual changes

CSS variables are the main public styling surface inside the shadow root. Use them before you inject custom CSS.

This approach keeps the normal fallback chain in place:

1. explicit override variables
2. --trees-theme-* variables from theme helpers
3. library defaults

For the token families behind those variables, read Styling and theming.

Match an editor palette with themeToTreeStyles(...)

Use themeToTreeStyles(...) when your app already has a VS Code or Shiki-style theme object. It maps that theme to host styles. It also maps the theme to the --trees-theme-* variables that the tree understands.

This helper gives you matching panel colors, selection colors, search-field colors, and Git-status colors. You do not rebuild the theme system by hand.

Set density with density

Pass density to useFileTree, preloadFileTree, or the vanilla FileTree constructor. This option sets row height and spacing together. The keyword form ('compact', 'default', 'relaxed') sets both values at once. The numeric form keeps the default row height and sets a custom spacing factor. Every runtime paints --trees-item-height and --trees-density-override onto the host from the resolved density. The runtimes are vanilla CSR, vanilla SSR, React CSR, and React SSR. This step keeps the virtualized row height and the painted row height aligned. Caller-set inline values on the host still win. So you can override either variable directly for a one-off. Set itemHeight only when you need a row height that does not match a preset.

The keyword presets are exported as FILE_TREE_DENSITY_PRESETS. So SSR helpers such as initialVisibleRowCount can divide by the preset row height. They do not hard-code it.

Choose the right styling layer

Use:

• host styles for layout and panel framing
• CSS variables for product-specific appearance changes inside the tree
• themeToTreeStyles(...) when the tree must inherit an editor palette
• getFileTreeContainer() in vanilla when runtime code needs the mounted host element

Add explicit overrides on top when the imported theme is close but not final.

unsafeCSS is the escape hatch

Use unsafeCSS for cases that the supported host and variable surfaces cannot express. Keep it small, local, and secondary.

Do not start here. Do not rebuild the whole visual system from raw selectors. For a broad lookup of the supported styling surfaces, read Styling and theming. For icon-specific appearance changes, continue with Customize icons.

Customize icons

Start with the built-in icon sets. Then add targeted remaps only where your product needs them. Most apps do not need to replace the whole icon system.

Start with the built-in icon sets

Trees includes three built-in sets:

• minimal for low-noise file and folder visuals
• standard for common language and file-type recognition
• complete for the broadest built-in coverage

Pass the set name directly when you need only a different baseline.

Adjust color mode before you remap icons

Built-in sets use semantic icon colors by default. Turn the colors off before you use a sprite sheet. Do this when the product needs a quieter or monochrome look.

Use the styling system for broader appearance control. Do not treat icons as a parallel theme surface. Read Style and theme the tree.

Use the object form for targeted remaps

Switch to FileTreeIconConfig when a plain set name is not enough. The practical remap surfaces are:

• remap for built-in slots such as the generic file icon, chevron, dot, or lock
• byFileName for exact basenames such as package.json
• byFileExtension for suffixes such as ts or spec.ts
• byFileNameContains for broader patterns such as dockerfile

This approach keeps the built-in mapping for every icon that you did not change.

Rule precedence matters

File-specific rules win over broader rules. Trees resolves icons in this order:

1. exact basename matches
2. basename-contains matches
3. extension matches, and the more specific suffix wins
4. the chosen built-in set
5. the generic file-slot remap or fallback

For the full lookup contract, read Icons.

Use a sprite sheet only for advanced cases

Use spriteSheet in two cases. Use it when you already have branded SVG symbols. Also use it when you need a few custom symbols next to the built-in set.

Keep the contract simple. Provide <symbol> definitions. Then point remap rules at those symbols. Do not make sprite sheets the default docs path.

Show Git status and row annotations

Use built-in gitStatus when the signal is Git-like. Use renderRowDecoration when the row needs product-specific metadata that is not Git state.

Start with built-in gitStatus

gitStatus is the default row-signal path. It attaches statuses to canonical paths. Folders can reflect changed descendants automatically.

Trees supports these built-in statuses:

• added
• modified
• deleted
• ignored
• renamed
• untracked

This is the shortest path when the row signal already matches Git semantics.

Know when gitStatus is enough

Use gitStatus only when the meaning is Git-like. Do not invent fake Git state only to show a badge. Let Trees own the built-in status lane. Let the styling system control how those signals look.

Update status sets over time

Replace the current status data directly when the surrounding app changes. Examples are new commits, branches, comparison views, or status visibility.

This step keeps the runtime accurate. It does not promise a filesystem watcher or a repo-sync framework.

Add custom row annotations with renderRowDecoration

Use renderRowDecoration when the row needs metadata that is not Git-like.

Good fits include generated-file markers, remote-storage indicators, validation markers, and short secondary labels.

Choose between the two paths

Use:

• gitStatus when the meaning is Git-like
• renderRowDecoration for everything else
• both together when a row needs Git state and one extra product-specific signal

Keep annotations short and easy to read. Give a decoration accessible text or a tooltip when it affects user decisions.

Keep styling separate from annotation meaning

Keep Git-status colors and decoration visuals in the same appearance system as the rest of the tree. Use the styling and theming controls for color. Do not add a second theme layer for annotations.

For that part of the API, read Style and theme the tree and Styling and theming.

Handle large trees efficiently

To make large trees fast, first reduce unnecessary client work. Shape and order the data before it reaches the UI. Then tune rendering only where the visible window needs help.

Start with the main recommendation

Use:

• raw paths for small demos and low-ceremony cases
• preparedInput for larger trees
• preparePresortedFileTreeInput(...) when the server already owns the final order

This order matters. Do not go straight to the rendering knobs while the client still does avoidable shape or sort work.

Prepare input before it reaches the client

For larger trees, move the shape work out of the UI. Prepared input is the scale-oriented public path.

Use prepareFileTreeInput(...) instead when you have only an unsorted path list. In both cases, pass the prepared result into React, vanilla, or SSR hydration.

Keep rendering work small

Trees already virtualizes the visible row window. Most apps do not need custom virtualization primitives.

The main rendering knobs are:

• the host element CSS height, because layout sets the steady-state viewport size
• initialVisibleRowCount, to budget SSR or first-render work before measurement
• density, when your design changes the row density enough to matter. Pass 'compact' | 'default' | 'relaxed' or a custom numeric factor. This option sets both the row height and the spacing in one place. Use itemHeight only when you need a row height that does not match a preset.
• overscan, to trade a little extra work for smoother scrolling

Give the rendered tree host a real CSS height. The row-count hint only shapes the first render. The browser then measures the actual viewport.

Keep the language outcome-focused. The tree mounts the visible slice and a small buffer around it.

Expansion and search still affect scale

Prepared input lowers the cost to shape the data. But expansion and search still change how many rows stay visible at once. Large expanded trees and broad search results can widen the mounted window.

This is another reason to start with the input story first. Do not recompute the tree shape in the client while the visible tree also changes often.

SSR and hydration pair naturally with prepared input

Large trees often benefit from server preload. The same scale rule applies. Prepare or presort the input on the server one time. Preload the tree one time. Then let the client hydrate that work. Do not recompute it.

Read SSR when first paint matters. Read SSR API when you need the handoff contract.

Common pitfalls

Avoid these patterns when the tree grows:

• you send only raw paths for huge server-known datasets
• you re-sort on the client after the server already chose the order
• you use low-level virtualization ideas as the first fix
• you rebuild the model when resetPaths(...) with matching prepared input does the job

What to read next

• Shape tree data for fast rendering for the shared input story
• Shared concepts for the cross-runtime rendering knobs
• SSR for server-preload-first rendering

SSR

Use SSR when the tree must arrive from the server with a fast first paint. The tree then becomes interactive on the client. SSR is not a third primary runtime. It is a preload-and-hydrate layer over the same React or vanilla model.

Start with the server step

Import the preload helpers from @pierre/trees/ssr. Call preloadFileTree(...) on the server. Treat the result as one opaque handoff object.

The rendered container still sets the steady-state height. initialVisibleRowCount is only a first-render hint for SSR and hydration. The browser then measures the real viewport.

Do not unpack the payload field by field in application code. Pass it forward unchanged.

Core invariants

The server and the client must use the same tree-defining options. Match the same input source. Match the same id discipline. Match the same state-affecting options that change the first rendered tree.

The result is a hydration mismatch when the server preloads one tree and the client builds a different one.

React flow

React still creates the model with useFileTree(...). The one difference is that the wrapper receives the opaque handoff object as preloadedData.

The model stays primary. preloadedData only starts hydration.

Vanilla flow

Vanilla uses the same preload step. But the client hydrates the server-rendered container that is already in the page.

Render normally instead of hydrating when that server-rendered container is missing.

Keep the payload opaque

In docs and application code, call the preload result an SSR payload or handoff object. React uses it as preloadedData. Vanilla hydrates existing server markup. Both flows reuse the same server work. Neither flow teaches the payload internals as the main story.

Pair SSR with prepared input for large trees

Large-tree SSR works best when the server already owns the expensive shape work. Prepare or presort the input on the server. Preload one time. Then let the client hydrate that same result.

Advanced note: declarative shadow DOM

The preloaded path uses declarative shadow DOM. In React, the packaged wrapper handles the host ownership details that it needs for hydration. Use the runtime behavior. Do not write custom DOM diffing or raw payload plumbing.

For the API-level handoff contract, read SSR API.

Reference

Shared concepts

This page owns the cross-runtime language for Trees. React, vanilla, and SSR all use the same path-first identity model. They use the same tree-defining inputs. They use the same mutation vocabulary.

Path-first identity

Canonical path strings are the public identity for tree items. Use paths for:

• selection values
• focused-item lookups
• search matches
• rename and drag-and-drop events
• Git status attachment
• row annotations

Files and directories share the same identity space. The APIs mark the item kind when that difference matters.

Input shapes

Trees accepts three related input shapes:

• paths: the low-ceremony path for demos, tests, and small static trees
• preparedInput: the recommended scale-oriented input shape
• presorted prepared input: the highest-performance prepared-input path when the server already knows the final order

Use prepareFileTreeInput(...) and preparePresortedFileTreeInput(...) from @pierre/trees to create the prepared forms. Treat prepared input as an opaque tree-input object. Do not build the shape by hand.

Shared option groups

This table lists the shared meaning of the public options surface across runtimes.

Tree-shape options

The tree-shape options are paths, preparedInput, initialExpansion, initialExpandedPaths, flattenEmptyDirectories, and sort.

Use them to answer three questions:

1. where the tree data comes from
2. what the initial visible shape must be
3. whether the client must still shape or sort the data

For the recommended setup, read Shape tree data for fast rendering.

Search mode semantics

Trees supports three search modes:

• hide-non-matches: shows only the matches and the ancestor chain that keeps them navigable. This is the guide default.
• collapse-non-matches: keeps the matching paths and the ancestor chain visible. It collapses unrelated branches out of the way.
• expand-matches: expands the matching branches into the surrounding tree context. It keeps non-matching rows visible.

React and vanilla use the same search modes. Runtime pages must not redefine them.

Selection, focus, and item handles

Selection is path-based. Focus is path-based. Item handles are path-oriented helpers for a known item.

Common lookup topics are:

• get an item by path
• read the focused and selected state
• focus, select, toggle, or deselect through the model or item handle
• expand, collapse, or toggle directories through a directory handle

Read Navigate selection, focus, and search for workflows. Read React API for selector hooks. Read Vanilla API for direct class methods.

Interaction and editing options

dragAndDrop, renaming, and composition are the runtime-agnostic editing surfaces. They share the same path-first event model. The React and vanilla integration points differ.

Read Rename, drag, and trigger item actions for the user-facing workflows that build on those options.

Appearance and annotation options

gitStatus, icons, renderRowDecoration, and unsafeCSS all affect how rows look. But they do different jobs:

• gitStatus is the built-in Git-style signal lane
• icons controls icon sets, remaps, and sprite-sheet extension
• renderRowDecoration adds non-Git row metadata
• unsafeCSS is the narrow fallback when public styling surfaces are not enough

For deeper lookup, read Styling and theming and Icons.

Scale and rendering settings

initialVisibleRowCount, density, itemHeight, and overscan are rendering knobs, not onboarding concepts. The rendered container sets the steady-state height. These options only tune the first-render budget, the visual density, and the virtualized row window.

For density, use the density keyword ('compact' | 'default' | 'relaxed') or a numeric factor. It sets both the row height and the spacing in one place. The React <FileTree> wrapper paints --trees-item-height and --trees-density-override for you. Use itemHeight only when you need a row height that does not match a preset.

Read Handle large trees efficiently when scale becomes the real problem.

Mutation vocabulary

Trees exposes semantic tree mutations, not DOM events. The shared mutation terms are:

• add
• remove
• move
• batch
• resetPaths
• onMutation

Mutation payloads stay path-first. Reset events also report whether prepared input was involved. Invalidation metadata reports whether the canonical state or the projected visible state changed.

Use these events to sync adjacent UI, analytics, or persistence layers. Do not turn them into a filesystem-sync tutorial.

Opaque SSR payload framing

Server preload returns one handoff object. Pass it forward unchanged.

React uses that handoff as preloadedData. Vanilla hydrates existing server markup through hydrate({ fileTreeContainer }). Neither runtime must teach the field-by-field payload steps as the main story.

For the preload and hydration contract, read SSR API.

React API

The React entry point lives in @pierre/trees/react. It is a thin React integration layer over the same imperative model that the vanilla runtime uses.

React model-first story

Start with useFileTree(options). Do not build a large controlled component. The hook creates one stable model for the component lifetime. Later option changes do not reconfigure the model. Update the model through model methods instead.

For the shared option meanings behind that call, read Shared concepts.

useFileTree(...)

useFileTree(...):

• accepts the shared tree-options surface
• creates the model one time
• cleans up the model when the React component unmounts
• returns UseFileTreeResult, which currently exposes model

Use model methods when the tree changes after mount. The methods include resetPaths(...), setComposition(...), setGitStatus(...), setIcons(...), and the search or mutation methods.

<FileTree />

The React component mounts the model into a host element.

Primary props:

• model
• normal host HTML attributes such as className, style, and id

React-only props:

• header
• renderContextMenu
• preloadedData

Behavior notes:

• it renders the model into the host element
• it hydrates instead of rendering fresh when matching preloaded content is already present
• it uses id ?? preloadedData?.id for host identity during hydration
• header and renderContextMenu add React rendering onto the model composition surface

Reading tree state from React

React components read from the model through selector hooks. React components write back through model methods.

Common read patterns include:

• selected paths for sibling panels or action bars
• search state for search inputs and result counts
• custom derived snapshots such as "is this path focused?"

Selector hooks

useFileTreeSelector(model, selector, equality?)

• generic bridge from the imperative model into React
• returns a selected snapshot from the current model
• accepts an optional equality function when the selected value needs custom comparison

useFileTreeSelection(model)

• convenience hook for readonly string[] selected paths

useFileTreeSearch(model)

• returns the current search snapshot and the model-backed actions
• snapshot fields: isOpen, matchingPaths, value
• actions: open(initialValue?), close(), setValue(value), focusNextMatch(), focusPreviousMatch()

Writing to the model from React

React writes through the same imperative model methods that the vanilla runtime exposes.

Typical write paths are:

• focus and selection methods on the model or item handles. This includes scrollToPath(...), which reveals a path without moving DOM focus and makes optional model focus changes.
• visible-tree traversal through focusFirstItem(), focusLastItem(), focusNextItem(), focusPreviousItem(), and focusParentItem().
• visible row inspection through getFocusedIndex(), getVisibleCount(), and getVisibleRows(start, end) when surrounding UI needs custom navigation.
• search methods such as setSearch(...) and openSearch(...)
• mutation methods such as add(...), remove(...), move(...), batch(...), and resetPaths(...)
• runtime reconfiguration methods such as setComposition(...), setGitStatus(...), and setIcons(...)

React-specific composition surface

React adds two high-level composition props on top of the model:

• header for React-rendered header content
• renderContextMenu(item, context) for React-rendered context menus

Use them when the menu or header belongs in React. The shared meaning of the composition options is in Shared concepts.

Mutation and subscriptions from React

Use selector hooks when React UI needs reactive reads. Use model.onMutation(...) when you need semantic side effects. Examples are persistence, logging, or analytics around add, remove, move, reset, or batch operations.

Hydration boundary

The React runtime uses server preload through preloadedData on <FileTree />. The model still comes from useFileTree(...). The client must use matching tree-defining options.

For the preload contract, read SSR API. For workflow guidance, read SSR.

Appearance boundary

Style the React host with normal host props such as className and style. For deeper lookup, read Styling and theming and Icons.

Vanilla API

The vanilla runtime lives at the package root, @pierre/trees. new FileTree(...) is the runtime entry point and the imperative model surface.

Class-first story

Start with new FileTree(options). Then mount the instance.

For shared option meanings, read Shared concepts.

Constructor surface

new FileTree(options):

• accepts the shared options surface
• creates the model one time
• expects later updates through model methods; do not rebuild option objects for every render

Mounting and lifecycle

render(...)

• accepts { fileTreeContainer } when you already own the host element
• accepts { containerWrapper } when the runtime must create and append the host for you

hydrate({ fileTreeContainer })

• attaches the model to server-rendered tree markup already in the page

unmount()

• removes the mounted runtime and keeps the model available

cleanUp()

• final teardown: unmount, subscription cleanup, and model destruction

getFileTreeContainer()

• returns the mounted host element after render or hydrate

Read APIs

Common read methods are:

• getItem(path)
• getFocusedItem()
• getFocusedPath()
• getFocusedIndex()
• getVisibleCount()
• getVisibleRows(start, end)
• getSelectedPaths()
• getComposition()
• isSearchOpen()
• getSearchValue()
• getSearchMatchingPaths()

These reads stay path-oriented and model-oriented. They do not ask you to infer the tree state from DOM order.

Item handles

getItem(path) returns a file handle, a directory handle, or null.

Shared handle actions:

• getPath()
• focus()
• select()
• toggleSelect()
• deselect()

Directory-only actions:

• expand()
• collapse()
• toggle()

Write and control APIs

Focus and selection control:

• focusPath(path)
• focusNearestPath(path | null)
• focusFirstItem() / focusLastItem()
• focusNextItem() / focusPreviousItem()
• focusParentItem()
• scrollToPath(path, { offset: 'top' | 'center' | 'nearest', focus?: boolean })
• startRenaming(path?)
• item-handle selection and focus methods

scrollToPath(...) scrolls the virtualizer without moving DOM focus. It updates model focus by default. Pass focus: false to keep model focus unchanged.

The traversal methods follow the current visible tree, including its active expansion and search state. getVisibleRows(start, end) uses inclusive row indexes and returns path-first row metadata for building custom navigation.

Search control:

• setSearch(value)
• openSearch(initialValue?)
• closeSearch()
• focusNextSearchMatch()
• focusPreviousSearchMatch()

Data and mutation control:

• add(path)
• remove(path, options?)
• move(fromPath, toPath, options?)
• batch(operations)
• resetPaths(paths, options?)
• onMutation(type, handler)

Runtime reconfiguration helpers:

• setComposition(composition?)
• setGitStatus(gitStatus?)
• setIcons(icons?)

Subscriptions and external systems

Use subscribe(listener) when any tree change must refresh a derived snapshot. Use onMutation(...) when add, remove, move, reset, or batch intent matters.

This separation keeps model subscriptions for state reads. It keeps mutation events for semantic side effects.

Composition surface

The composition surface covers:

• header composition
• context-menu composition
• runtime updates through setComposition(...)

Read Rename, drag, and trigger item actions for workflow-level guidance.

Hydration boundary

This page names only the vanilla hydration entry point: hydrate({ fileTreeContainer }). The full server-preload-first contract is in SSR API.

Appearance boundary

This page names the runtime touchpoints such as getFileTreeContainer(), setGitStatus(...), and setIcons(...). For styling variables, theme helpers, and unsafeCSS, read Styling and theming. For icon remaps and icon-set lookup, read Icons.

SSR API

The SSR entry point lives in @pierre/trees/ssr. It owns server preload and the server-to-client handoff contract.

Server-preload-first contract

Start with the server step, not the client step. Call preloadFileTree(options) on the server. Then pass the returned value forward as one opaque handoff object.

Hydration reuses that server work. It is not a separate rendering strategy with a different public data model.

preloadFileTree(...)

preloadFileTree(...):

• accepts the shared FileTreeOptions surface
• pre-renders the tree for first paint
• returns an opaque SSR payload

The current exported payload type name is FileTreeSsrPayload. But the docs-facing rule stays the same. Pass it through unchanged.

serializeFileTreeSsrPayload(...)

serializeFileTreeSsrPayload(payload, mode?) turns the preloaded payload into a full host-markup string.

Use it when your server integration needs a serialized HTML string. This avoids a framework-specific render boundary. The payload still stays opaque at the docs level.

Opaque payload framing

Treat the preload result as a handoff object. Do not treat it as a field-by-field integration surface.

Docs can name the runtime touchpoints that use it:

• React passes the payload as preloadedData
• Vanilla hydrates the server-rendered tree already in the page with hydrate({ fileTreeContainer })

Do not make the raw payload fields the public story.

Handoff rules

The server and the client must use the same tree-defining options.

Match:

• the same path source (paths, prepared input, or presorted prepared input)
• the same id discipline
• the same expansion and search options when they change the initial rendered tree
• the same appearance options when they change the initial markup or icon output

A mismatch is not a supported partial merge. It produces a hydration mismatch or an incorrect first state.

Prepared input and hydration

Hydration works with raw paths or prepared input. But the recommended scale path is server-prepared input with matching client consumption.

For the shared input model behind that rule, read Shared concepts.

React handoff

React still creates the model with useFileTree(...). Then it passes the payload to <FileTree model={model} preloadedData={payload} />.

For the full runtime surface, read React API. For the workflow guide, read SSR.

Vanilla handoff

Vanilla emits the server-rendered tree into the page first. Then it creates new FileTree(options) on the client. Then it calls fileTree.hydrate({ fileTreeContainer }) against the existing host.

For the full runtime surface, read Vanilla API. For the workflow guide, read SSR.

Advanced note boundary

Keep any note about declarative shadow DOM or hydration warnings short and secondary. This page owns the public handoff contract, not the DOM internals.

Styling and theming

This page is the lookup reference for host styling, CSS-variable families, themeToTreeStyles(...), and the unsafeCSS escape hatch.

Styling entry points

Host styling comes first.

• React: use normal host className and style props on <FileTree model={...} />
• Vanilla: style the mounted host that getFileTreeContainer() returns

Host styles own width, height, borders, background, and panel placement. CSS variables control the UI inside that host.

CSS custom property families

The tree styling surface uses variable families, not one flat list.

Core families include:

• panel, background, and foreground tokens
• hover, selection, and focus tokens
• input and search tokens
• Git-status color tokens
• icon color tokens for supported built-in icon sets

Fallback precedence

Trees resolves styling in this order:

1. explicit override variables such as --trees-*-override
2. --trees-theme-* variables from theme helpers
3. library defaults

So themeToTreeStyles(...) fills the middle layer. Direct overrides still win.

themeToTreeStyles(...)

themeToTreeStyles(theme) maps a VS Code or Shiki-style theme object into host styles. It also maps the theme to the --trees-theme-* variables that the tree understands.

Input shape:

• TreeThemeInput
• key fields: type, bg, fg, colors

Output shape:

• TreeThemeStyles
• compatible with React inline styles and vanilla host-style assignment

The helper covers panel colors, selection colors, focus rings, input colors, and Git-status colors. Explicit overrides can still replace any derived token later.

Runtime touchpoints

React:

• keep styling on the host element through normal className and style props
• there is no separate React-only styling API beyond the shared tree options

Vanilla:

• apply styles through the host or container that you already own
• getFileTreeContainer() is the handoff back to application styling code

unsafeCSS escape hatch

unsafeCSS is the secondary path. Use it only when the supported host and variable surfaces cannot express the customization.

Reference topics:

• the option name and public package surface
• shadow-root CSS injection at a high level
• a warning that this is the exception path, not the default styling story

Keep it narrow. Do not make it a raw stylesheet-asset strategy.

Related pages

• Style and theme the tree for the walkthrough
• Icons for icon-specific configuration
• Show Git status and row annotations for signal meaning

Icons

This page is the lookup reference for icon sets, icon remaps, sprite-sheet extension, and icon-specific configuration rules.

Entry points

Built-in set selection:

• icons: 'minimal' | 'standard' | 'complete'
• minimal keeps the visual noise low
• standard adds common language and file-type icons
• complete has the broadest built-in coverage

Object configuration:

• use FileTreeIconConfig when a string set is not enough
• combine a base set with color toggles, slot remaps, or file-specific remaps

Configuration shape

Base set and color mode:

• set?: 'minimal' | 'standard' | 'complete' | 'none'
• colored?: boolean

set: 'none' turns off the built-in file-type mappings. File rows still fall back to the generic file icon. Remaps can replace that icon.

Sprite-sheet extension:

• spriteSheet?: string
• supply an SVG string with <symbol> definitions that remaps can target

Built-in slot remapping:

• remap?: Record<string, RemappedIcon>
• common slots: chevron, generic file icon, modified-state dot, locked-path icon

File-specific remapping:

• byFileName for exact basename matches such as package.json
• byFileNameContains for basename substring rules such as dockerfile
• byFileExtension for extension rules without a leading dot, and for multi-part suffixes such as spec.ts

Resolution order

File icon lookup resolves in this order:

1. exact basename match from byFileName
2. basename-contains match from byFileNameContains
3. extension match from byFileExtension, and the more specific suffix wins
4. built-in set mapping
5. generic file-slot remap or fallback

So spec.ts wins over ts when both rules exist.

RemappedIcon shape

RemappedIcon supports two forms:

• a string symbol id
• an object with name, and optional width, height, and viewBox

Use the object form when the replacement symbol needs non-default geometry metadata.

Runtime touchpoints

React:

• pass the icon configuration through the model options for useFileTree(...)

Vanilla:

• pass the icon configuration at construction time
• update it later with setIcons(...)

For the runtime-specific lookup around those touchpoints, read React API and Vanilla API.

Icon color interplay

Turn off the built-in colored icons with colored: false. The token lookup and the fallback precedence for icon colors are in Styling and theming.

Related pages

• Customize icons for the walkthrough
• Style and theme the tree for broader appearance changes