The tree renders inside a shadow root, uses CSS custom properties for theming,
and keeps its public API keyed by canonical paths instead of internal numeric
IDs.
Install
bun add @pierre/trees
Vanilla usage
import { FileTree } from '@pierre/trees';const mount = document.getElementById('mount')!;mount.style.height = '320px';const tree = new FileTree({ flattenEmptyDirectories: true, initialExpansion: 'open', paths: ['README.md', 'src/index.ts', 'src/components/Button.tsx'], search: true,});tree.render({ containerWrapper: mount });
Use ${payload.outerStart}${payload.shadowHtml}${payload.outerEnd} when the
HTML parser will see the markup directly, such as a full server-rendered HTML
response. Use ${payload.domOuterStart}${payload.shadowHtml}${payload.outerEnd}
when you need to insert the full container string through DOM APIs like
innerHTML or dangerouslySetInnerHTML. Pass { id, shadowHtml } to the React
component as preloadedData.
Styling
The host element and shadow root read CSS variables such as:
--trees-selected-bg-override
--trees-border-color-override
--trees-fg-override
--trees-theme-*
You can translate a Shiki / VS Code style theme into tree CSS with
themeToTreeStyles():
import { themeToTreeStyles } from '@pierre/trees';const styles = themeToTreeStyles(theme);
If CSS variables are not enough, unsafeCSS injects raw CSS into the tree
shadow root:
const tree = new FileTree({ paths, unsafeCSS: ` button[data-type='item'][data-item-selected] { border-radius: 999px; } `,});
Treat unsafeCSS as an escape hatch. Start with host styles, CSS variables, and
themeToTreeStyles() first.
If you need the custom element registration side effect directly, import:
import '@pierre/trees/web-components';
Icons, git status, and composition
The root package exports the icon and git-status types used by the tree model,
including:
FileTreeIcons
FileTreeIconConfig
GitStatusEntry
ContextMenuItem
ContextMenuOpenContext
ContextMenuTriggerMode
ContextMenuButtonVisibility
Header and context-menu composition are configured through the tree options.
Rows, search state, drag/drop targets, and mutation events all report canonical
paths.
const tree = new FileTree({ composition: { contextMenu: { enabled: true, }, }, paths,});
When the context menu is enabled without an explicit triggerMode, it defaults
to 'right-click'. Set triggerMode: 'button' or triggerMode: 'both' when
you want the dedicated right-side action lane. In those button-capable modes,
buttonVisibility defaults to 'when-needed'; set it to 'always' to show
decorative per-row affordances while the tree still uses one real floating
trigger button and one slotted menu surface.
renderRowDecoration now occupies its own flexible lane. Built-in git status
rendering stays separate in the next fixed lane, so custom decoration content,
git status, and the context-menu affordance can appear on the same row without
overriding each other.
Development
From packages/trees:
bun testbun run test:e2ebun run benchmarkbun run benchmark:file-tree-get-itembun run profile:file-treebun run tscbun run build