Tree View
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
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add tree-viewAlso works with shadcn:
npx shadcn@latest add @ritla/tree-viewDependencies it brings
@phosphor-icons/reactOr 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
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}).
API reference
TreeView
| Prop | Type | Default | Description |
|---|---|---|---|
items | { id, label, children? }[] | None | The tree; an item with children is a branch, even when they're empty. |
expanded / defaultExpanded | string[] | None | The open branches. |
onExpandedChange | (ids: string[]) => void | None | Called when a branch opens or closes. |
selected / defaultSelected | string | null | None | The selected row. |
onSelectedChange | (id: string) => void | None | Called when a row is selected. |
showIcons | boolean | true | Figma's Show icon: the folder and file icons. |
aria-label | string | None | The 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 to | Use | Why |
|---|---|---|
| Browse nested folders or categories | Tree view | Open only the branches you need. |
| Show a flat list of items | A list or a table | No hierarchy to open. |
| Group a few sections of content on one page | Accordion | Headings with content, not files. |
| Move between areas of the app | Sheet, Side navigation or Tabs | A tree for navigation hides where you are. |
| Find one item in a large hierarchy | Search with the tree | Typing 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.
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.
| Key | Action |
|---|---|
| Tab | Enters the tree once, on the selected row. |
| ArrowDownArrowUp | Between the visible rows. |
| ArrowRight | Opens a closed branch, or moves to its first child. ArrowLeft in Arabic. |
| ArrowLeft | Closes an open branch, or moves to the parent. ArrowRight in Arabic. |
| HomeEnd | To the first or last row. |
| EnterSpace | Selects the row. |
ARIA
- A named
role="tree"; each row is atreeitemwitharia-level,aria-setsize,aria-posinset,aria-expandedon branches andaria-selected. - Don't go deeper than four levels, and don't use a tree to move between app sections.
Do
role="tree"andtreeitem, witharia-expandedon branches andaria-selectedon 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-14Regular; 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.
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)