Árvore

Navegue por pastas aninhadas e conteúdo estruturado com ramos expansíveis, transições suaves de desfoque e navegação pelo teclado.

Instalação

Você pode adicionar a árvore usando nossa CLI ou manualmente:

Modo escuro pronto - este componente segue tokens semânticos BoardUI automaticamente. Configurar a mudança de tema.

O CLI copia a fonte do componente (com suas dependências internas) em seu projeto e instala quaisquer pacotes npm necessários.

npx boardui@latest add tree-view

Usando um pacote de UI compartilhado ou aliases de importação personalizados? Configure seus caminhos de instalação antes de executar o CLI. Exemplos de copy-paste usam as importações padrão.

Estado controlado e dados dinâmicos

Mantenha a expansão e a seleção no seu próprio estado com expandedKeys e selectedKeys. Utilização TreeViewCollection para renderizar dados aninhados recursivamente. Cada item precisa de um identificador único e estável id.

Os ramos expandem e recolhem com transições suaves de altura, opacidade e desfoque. As linhas que saem deixam imediatamente a navegação pelo teclado, e a preferência por movimento reduzido desativa a animação.

Workspace

Selected: logo

import { useState } from "react";import type { Key, Selection } from "react-aria-components";import { TreeView, TreeViewCollection, TreeViewItem } from "@/components/base/tree-view/tree-view"; interface FileNode { id: string; name: string; children?: FileNode[];} const files: FileNode[] = [ { id: "design", name: "Design", children: [ { id: "logo", name: "Logo.svg" }, { id: "colors", name: "Colors.fig" }, ] }, { id: "notes", name: "Project notes.md" },]; function renderFile(item: FileNode) { return ( <TreeViewItem id={item.id} label={item.name}> <TreeViewCollection items={item.children ?? []}>{renderFile}</TreeViewCollection> </TreeViewItem> );} export function Example() { const [expandedKeys, setExpandedKeys] = useState<Set<Key>>(new Set(["design"])); const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set(["logo"])); return ( <TreeView aria-label="Workspace files" items={files} expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys} selectedKeys={selectedKeys} onSelectionChange={setSelectedKeys} > {renderFile} </TreeView> );}

Seleção múltipla

Definir selectionMode="multiple" para alternar itens de forma independente. Segure Shift para selecionar um intervalo pelo teclado. A seleção única é o padrão; use selectionMode="none" com onAction para uma árvore que apenas executa ações.

2 items selected

<TreeView aria-label="Documents to share" selectionMode="multiple" defaultExpandedKeys={["documents"]} defaultSelectedKeys={["overview", "guidelines"]}> <TreeViewItem id="documents" label="Documents" trailingContent="3 files"> <TreeViewItem id="overview" label="Overview.md" /> <TreeViewItem id="guidelines" label="Guidelines.md" /> <TreeViewItem id="changelog" label="Changelog.md" /> </TreeViewItem></TreeView>

Tamanhos, ícones e estados

Utilização size="sm" para linhas compactas e showGuides={false} para ocultar as linhas-guia. Os ramos recebem ícones de pasta automaticamente; passe um componente Remix Icon para ícone ou expandedIcon para personalizá-los. Itens desativados impedem a interação, e renderEmptyState fornece uma mensagem para o estado vazio.

No matching files.
import { RiFolder3Line } from "@remixicon/react"; <TreeView aria-label="Repository files" size="sm" showGuides={false}> <TreeViewItem id="index" label="index.tsx" /> <TreeViewItem id="private" label="Private files" isDisabled trailingContent="Restricted" /> <TreeViewItem id="archive" label="Archive" icon={RiFolder3Line} trailingContent="Empty" /></TreeView> <TreeView aria-label="Search results" renderEmptyState={() => "No matching files."}> {[]}</TreeView>

Da direita para a esquerda

Defina a localidade com DirectionProvider. Recuos, linhas-guia, ícones de expansão e navegação horizontal pelo teclado seguem a direção de leitura.

import { DirectionProvider } from "@/components/foundations/direction/direction";import { TreeView, TreeViewItem } from "@/components/base/tree-view/tree-view"; <DirectionProvider locale="ar"> <TreeView aria-label="ملفات المشروع" defaultExpandedKeys={["project"]}> <TreeViewItem id="project" label="المشروع"> <TreeViewItem id="design" label="التصميم"> <TreeViewItem id="logo" label="الشعار.svg" /> </TreeViewItem> <TreeViewItem id="notes" label="الملاحظات.md" /> </TreeViewItem> </TreeView></DirectionProvider>

Navegação com teclado

Entre na árvore com Tab e use as setas para cima e para baixo para percorrer itens visíveis. A seta para a direita expande um ramo ou vai ao primeiro filho; a seta para a esquerda recolhe o ramo ou volta ao pai. Home e End vão ao primeiro e último item visível. Digite um rótulo para encontrá-lo e pressione Espaço para selecionar.

Forneça a cada árvore um aria-label ou aria-labelledby. Envolva as regiões RTL no componente do BoardUI DirectionProvider com a localidade apropriada; ícones de expansão, recuos e teclas horizontais seguem a direção automaticamente.