Direactree

Styling & accessibility

Pick a theme, appearance, and density, recolor the tree with CSS tokens, target row state with data attributes, and rely on the keyboard, screen-reader, motion, and contrast support that comes with it.

Stylesheet

import "direactree/direactree.css";

Import it once, in Next.js in the root layout. Since 0.4 the JavaScript adds no styles, so without this import the tree is unstyled. That also makes it work under a strict Content-Security-Policy and styled before JavaScript runs.

FileUse
direactree/direactree.cssThe rules as plain CSS. Load your own stylesheet after it to override.
direactree/direactree.layer.cssThe same rules inside @layer direactree. Any CSS in your app that is not in a layer wins over them, in any order, without !important.
NeitherStyle the tree from scratch with classNames and the data attributes below.

Theme, appearance, density

<Direactree
  structure={structure}
  theme="system"        // "light" | "dark" | "system"
  appearance="plain"    // "plain" | "card"
  density="comfortable" // "comfortable" | "compact"
  indent={20}
/>
  • theme: "system" (default) follows the operating system; "light" and "dark" stay fixed. To follow your app's own switch, pass its value: theme={isDark ? "dark" : "light"}.
  • appearance: "plain" (default) has no border or shadow, so the tree sits inside a sidebar or panel. Its background follows the theme. "card" adds a border, padding, shadow, and a boxed toolbox.
  • density: "comfortable" (default) has 28px rows and 14px text; "compact" has 22px rows and 13px text.
  • indent: the space added per level, 8 to 50 pixels.

Selection fills the whole row. Indent, guide lines, chevrons, and drop markers use logical CSS properties, so the tree mirrors correctly inside dir="rtl".

TRY ITTheme, appearance, density

The package's own colors, without the docs palette. Select a row and hover others to see the selection and hover states.

  • my-app
  • src
  • components
  • Button.tsx
  • Modal.tsx
  • Tooltip.tsx
  • index.ts
  • styles.css
  • package.json
  • README.md
props
<Direactree
  structure={structure}
  theme="light"
  appearance="plain"
  density="comfortable"
  indent={20}
/>

CSS tokens

Every color and size is a --direactree-* custom property on the .direactree root. Set them on your own class, or on one tree through style. The style prop is typed to accept these tokens, so TypeScript needs no cast:

<Direactree
  structure={structure}
  style={{ "--direactree-bg": "transparent", "--direactree-row-height": "24px" }}
/>
.project-explorer {
  --direactree-selected: #f3e6d6;
  --direactree-focus: #88572f;
  --direactree-radius: 4px;
}
<Direactree structure={structure} className="project-explorer" />

Load your stylesheet after direactree.css, because .project-explorer and the built-in .direactree rule have the same weight. With direactree.layer.css the order does not matter.

One color or two

The built-in colors are written with light-dark(light, dark). The root sets color-scheme from theme, and the browser picks the half that matches. A plain value applies to both themes: a light amber selection that looks right on the light theme puts a bright bar behind light text on the dark theme. Give each theme its own color with light-dark():

<Direactree
  structure={structure}
  style={{
    "--direactree-selected": "light-dark(#ede9fe, #4c1d95)",
    "--direactree-selected-fg": "light-dark(#4c1d95, #ede9fe)",
  }}
/>
TRY ITOne color or two

Pick the selection colors. With light-dark() each theme gets its own pair. Turn it off to see the same light color fail on the dark theme.

theme="light"
  • my-app
  • src
  • components
  • Button.tsx
  • Modal.tsx
  • Tooltip.tsx
  • index.ts
  • styles.css
  • package.json
  • README.md
theme="dark"
  • my-app
  • src
  • components
  • Button.tsx
  • Modal.tsx
  • Tooltip.tsx
  • index.ts
  • styles.css
  • package.json
  • README.md
style
style={{
  "--direactree-selected": "light-dark(#ede9fe, #4c1d95)",
  "--direactree-selected-fg": "light-dark(#4c1d95, #ede9fe)",
}}

To change many tokens for one fixed theme, select on data-direactree-theme. A theme="system" tree switches with the operating system, so use light-dark() for it:

.project-explorer[data-direactree-theme="dark"] {
  --direactree-surface: #191b17;
  --direactree-line: #3f3f46;
}

light-dark() needs Chrome 123, Safari 17.5, Firefox 120, or newer. The live examples on this site map the tokens to the documentation palette, so they follow this site's light and dark switch.

Token list

TokenUse
--direactree-surfaceTheme surface: the default background, the card, the sticky toolbox
--direactree-bgRoot background. Defaults to the surface; set transparent to show your page behind the tree.
--direactree-fgRoot text
--direactree-border, --direactree-dividerCard border, toolbox divider
--direactree-shadow, --direactree-shadow-hoverCard shadow
--direactree-row-height, --direactree-font-sizeRow height and text size, set by density
--direactree-radiusCorner radius of rows and buttons
--direactree-indentSpace per level, set by indent
--direactree-toolbox-button-sizeToolbox button size
--direactree-viewport-heightScroll height of a virtualized tree
--direactree-line, --direactree-line-hoverIndent guide lines
--direactree-hoverRow hover background
--direactree-name, --direactree-name-hoverRow text
--direactree-icon, --direactree-icon-hoverChevrons, icons, badges, muted text
--direactree-selected, --direactree-selected-fgSelected rows
--direactree-focusFocus outline
--direactree-matchSearch match background
--direactree-dragover, --direactree-dragover-borderDrop target box and drop line
--direactree-toolbox-bg, --direactree-toolbox-borderCard toolbox
--direactree-button-bg, --direactree-button-border, --direactree-button-hoverButtons
--direactree-input-bg, --direactree-input-borderName and search fields
--direactree-save-bg, --direactree-save-fg, --direactree-cancel-hoverEditor buttons
--direactree-confirm-bg, --direactree-confirm-border, --direactree-confirm-shadowDelete confirmation and context menu
--direactree-danger, --direactree-danger-bg, --direactree-danger-fg, --direactree-danger-border, --direactree-danger-hoverErrors and destructive buttons

State attributes

Each row is an <li class="direactree-row"> with its state in data attributes. Style these instead of depending on the markup depth:

AttributeValue
data-typefile or folder
data-stateopen or closed (folders)
data-depthLevel, from 0
data-selectedPresent when selected
data-activePresent on the focused selection
data-matchPresent when the row matches the search
data-lockedtrue on locked nodes
data-drop-positioninside, before, or after while dragging over it

The root also has data-direactree-theme, data-appearance, and data-density.

.direactree-row[data-type="folder"] > .direactree-item-anchor .direactree-item-name {
  font-weight: 500;
}

.direactree-row[data-locked] .direactree-item-name {
  opacity: 0.6;
}
TRY ITState attributes

Click a row to read the attributes on its <li>. Style with these instead of the markup depth, for example .direactree-row[data-type='folder'].

  • my-app
  • src
  • components
  • Button.tsx
  • Modal.tsx
  • Tooltip.tsx
  • index.ts
  • styles.css
  • package.json
  • README.md
<li> attributes
null

classNames

classNames adds your classes to each part of the tree, which suits Tailwind and other utility CSS:

<Direactree
  structure={structure}
  classNames={{
    root: "text-sm",
    row: "group",
    item: "rounded-md",
    label: "truncate",
    toolboxButton: "hover:bg-zinc-100",
  }}
/>

Slots: root, toolbox, toolboxButton, search, viewport, list, row, item, toggle, icon, label, badge, editor, menu, menuItem, confirm.

TRY ITclassNames

Each slot adds a class to one part of the tree. Turn it on to apply a few demo classes; with Tailwind you would pass utility classes the same way.

  • my-app
  • src
  • components
  • Button.tsx
  • Modal.tsx
  • Tooltip.tsx
  • index.ts
  • styles.css
  • package.json
  • README.md
classNames
{
  "root": "demo-cn-root",
  "row": "demo-cn-row",
  "item": "demo-cn-item",
  "label": "demo-cn-label",
  "toolbox": "demo-cn-toolbox",
  "toolboxButton": "demo-cn-button"
}

Screen readers

Direactree follows the WAI-ARIA tree pattern:

  • The list has role="tree", labelled by messages.directoryTree, and aria-multiselectable in multiple selection mode.
  • Each row is a treeitem with aria-level, aria-posinset, aria-setsize, and aria-selected. Folders have aria-expanded, and a loading folder has aria-busy.
  • The accessible name of a row is the node name, so icons and badges stay decorative.
  • Toolbox buttons, the search field, and the name field are labelled from messages.
  • Name errors and failed requests are announced with role="alert". A refused drop is announced through a polite live region. The loading row uses role="status".
  • The context menu uses role="menu" and menuitem. The delete confirmation is labelled by its title and description.

Translate every label with the messages prop.

Motion and contrast

  • With prefers-reduced-motion: reduce, transitions and animations are off.
  • With forced-colors: active (Windows high contrast), the tree uses system colors, and selection, focus, search matches, and drop targets stay visible.
  • Focus outlines sit inside the row, so they are not cut off by a scrolling container.