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 inserting 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-*
Translate a Shiki or VS Code 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.
Import the web-components entry point only when you need the custom element
registration side effect:
import '@pierre/trees/web-components';
Icons, git status, and composition
The root package exports icon, git-status, context-menu, drag/drop, mutation,
and row-decoration types. Public callbacks 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 to 'button' or 'both' for the
dedicated right-side action lane. In button-capable modes, buttonVisibility
defaults to 'when-needed'; set it to 'always' to show decorative per-row
affordances while the tree still uses one floating trigger button and one
slotted menu surface.
renderRowDecoration owns a flexible row lane. Built-in git status uses the
next fixed lane, so custom decoration content, git status, and the context-menu
affordance can appear on the same row.
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