Skip to content

Tree View

Get Ritla UI

Shows nested content, like folders of statements or a chart of accounts, and lets people open and close branches. Each level is indented one step; files sit under their folder.

Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add tree-view

    Also works with shadcn: npx shadcn@latest add @ritla/tree-view

  2. Dependencies it brings

    @phosphor-icons/react

  3. Or copy by hand

    Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.

Usage

tree-view.tsx
import { TreeView } from "@/components/ui/tree-view";<TreeView  aria-label="Documents"  items={[    { id: "statements", label: "Statements", children: [{ id: "q1", label: "Q1 2026" }] },    { id: "invoices", label: "Invoices", children: [] },  ]}  defaultExpanded={["statements"]}/>

Examples

Controlled selection

selected and expanded from the page: picking a file opens it beside the tree. Icons are off (showIcons={false}).

EnglishMirroredArabic
LTR →

API reference

TreeView

PropTypeDefaultDescription
items{ id, label, children? }[]NoneThe tree; an item with children is a branch, even when they're empty.
expanded / defaultExpandedstring[]NoneThe open branches.
onExpandedChange(ids: string[]) => voidNoneCalled when a branch opens or closes.
selected / defaultSelectedstring | nullNoneThe selected row.
onSelectedChange(id: string) => voidNoneCalled when a row is selected.
showIconsbooleantrueFigma's Show icon: the folder and file icons.
aria-labelstringNoneThe tree's name for screen readers.

Usage guidelines

A tree view shows a real hierarchy people browse and open step by step. When a tree fits, depth and order, selection and actions, how it indents from the right in Arabic, loading and empty branches, and the checks before handoff.

1. When a tree fits

Use a tree for a real hierarchy people browse and open step by step: document folders, a chart of accounts, product categories. If the structure is flat, or people search more than they browse, a list, a table or search serves them better.

You need toUseWhy
Browse nested folders or categoriesTree viewOpen only the branches you need.
Show a flat list of itemsA list or a tableNo hierarchy to open.
Group a few sections of content on one pageAccordionHeadings with content, not files.
Move between areas of the appSheet, Side navigation or TabsA tree for navigation hides where you are.
Find one item in a large hierarchySearch with the treeTyping beats opening five levels.

2. Depth and order

Keep the tree to four levels at most. Each level indents one step (16 px for the first, 48 more per level), branches show a caret and a folder, leaves a file one step deeper. List folders before files, then sort by name in the page language.

Do

  • Keep to four levels or fewer.
  • List branches before leaves, then sort by name.
  • Keep labels short; the full name can go in a tooltip.
  • Open the branch that holds the current item by default.

Don't

  • Nest deeper than four levels; flatten or add search.
  • Mix indent sizes between levels.
  • Open every branch at once.

3. Selection and actions

One row is selected at a time and shows the selected fill; the label keeps full contrast. Actions on a row (rename, move, delete) belong in a Menu button on the row or in a toolbar above the tree, not as buttons inside every row.

Do

  • Show one selected row with the selected fill and a readable label.
  • Put row actions in a menu or a toolbar.
  • Let a click on the caret open a branch without selecting it.

Don't

  • Make the selected row look disabled.
  • Put several buttons on every row.

4. Arabic and RTL

The RTL variant indents from the right. A closed branch's caret points left, toward the content inside, and turns down when open. Folder and file icons don't mirror. In code, the arrow keys follow the direction: ArrowLeft opens a branch in Arabic, ArrowRight closes it.

The tree indents from the right

Account documents in Arabic.

Do: RTL variantLevels step in from the right, and closed carets point left.
Don't: English tree with Arabic labelsLevels step in from the left, and the labels keep Latin fonts.

5. Loading and empty branches

Large trees load a branch's children when it opens. Show a spinner on the row while it loads, and a short message in an empty branch (“No documents yet”) instead of a caret that opens onto nothing.

Do

  • Load children when a branch opens, with a spinner on the row.
  • Show a message in empty branches.
  • Keep the tree's open state when people come back.

Don't

  • Freeze the whole tree while one branch loads.
  • Show a caret on a branch that has no children.

Before handoff

  • A real hierarchy of four levels or fewer.
  • Order, default open branches and selection are decided.
  • Loading and empty branches are designed.
  • Arabic screens use the RTL variant, indenting from the right.

Accessibility

Keyboard

Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.

KeyAction
TabEnters the tree once, on the selected row.
ArrowDownArrowUpBetween the visible rows.
ArrowRightOpens a closed branch, or moves to its first child. ArrowLeft in Arabic.
ArrowLeftCloses an open branch, or moves to the parent. ArrowRight in Arabic.
HomeEndTo the first or last row.
EnterSpaceSelects the row.

ARIA

  • A named role="tree"; each row is a treeitem with aria-level, aria-setsize, aria-posinset, aria-expanded on branches and aria-selected.
  • Don't go deeper than four levels, and don't use a tree to move between app sections.

Do

  • role="tree" and treeitem, with aria-expanded on branches and aria-selected on the selected row.
  • Up and Down move; Right opens or moves in (Left in Arabic), Left closes or moves out (Right in Arabic).
  • Home, End and first-letter typeahead.

Don't

  • Make every row its own Tab stop.
  • Rely on the folder icon alone to show a branch is open.

Arabic and RTL notes

Mirrors

  • Indents come from the right, a closed caret points left, and the selected bar sits on the right.
  • The open and close keys flip: ArrowLeft opens, ArrowRight closes.

Does not mirror

  • The folder and file icons.
Numerals
Numbers in labels stay as written.
Arabic typography
label-14 Regular; long labels truncate with an ellipsis.
Mixed-direction text
File extensions like .pdf reorder inside an Arabic label; drop them or put them in <bdi>.

Do

  • The RTL variant, indenting from the right.
  • Closed carets point left, open ones down.
  • Folder and file icons unmirrored.

Don't

  • Indent Arabic trees from the left.
  • Keep right-pointing carets in Arabic.

Checks it passes

The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.

  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space
  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)