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.
| File | Use |
|---|---|
direactree/direactree.css | The rules as plain CSS. Load your own stylesheet after it to override. |
direactree/direactree.layer.css | The same rules inside @layer direactree. Any CSS in your app that is not in a layer wins over them, in any order, without !important. |
| Neither | Style 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".
The package's own colors, without the docs palette. Select a row and hover others to see the selection and hover states.
<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)",
}}
/>
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.
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
| Token | Use |
|---|---|
--direactree-surface | Theme surface: the default background, the card, the sticky toolbox |
--direactree-bg | Root background. Defaults to the surface; set transparent to show your page behind the tree. |
--direactree-fg | Root text |
--direactree-border, --direactree-divider | Card border, toolbox divider |
--direactree-shadow, --direactree-shadow-hover | Card shadow |
--direactree-row-height, --direactree-font-size | Row height and text size, set by density |
--direactree-radius | Corner radius of rows and buttons |
--direactree-indent | Space per level, set by indent |
--direactree-toolbox-button-size | Toolbox button size |
--direactree-viewport-height | Scroll height of a virtualized tree |
--direactree-line, --direactree-line-hover | Indent guide lines |
--direactree-hover | Row hover background |
--direactree-name, --direactree-name-hover | Row text |
--direactree-icon, --direactree-icon-hover | Chevrons, icons, badges, muted text |
--direactree-selected, --direactree-selected-fg | Selected rows |
--direactree-focus | Focus outline |
--direactree-match | Search match background |
--direactree-dragover, --direactree-dragover-border | Drop target box and drop line |
--direactree-toolbox-bg, --direactree-toolbox-border | Card toolbox |
--direactree-button-bg, --direactree-button-border, --direactree-button-hover | Buttons |
--direactree-input-bg, --direactree-input-border | Name and search fields |
--direactree-save-bg, --direactree-save-fg, --direactree-cancel-hover | Editor buttons |
--direactree-confirm-bg, --direactree-confirm-border, --direactree-confirm-shadow | Delete confirmation and context menu |
--direactree-danger, --direactree-danger-bg, --direactree-danger-fg, --direactree-danger-border, --direactree-danger-hover | Errors 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:
| Attribute | Value |
|---|---|
data-type | file or folder |
data-state | open or closed (folders) |
data-depth | Level, from 0 |
data-selected | Present when selected |
data-active | Present on the focused selection |
data-match | Present when the row matches the search |
data-locked | true on locked nodes |
data-drop-position | inside, 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;
}
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'].
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.
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.
{
"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 bymessages.directoryTree, andaria-multiselectablein multiple selection mode. - Each row is a
treeitemwitharia-level,aria-posinset,aria-setsize, andaria-selected. Folders havearia-expanded, and a loading folder hasaria-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 usesrole="status". - The context menu uses
role="menu"andmenuitem. 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.