Árvore acessível construída a partir dos seus próprios <ul>/<li> aninhados (que continuam sendo uma lista legível sem JavaScript): suporte completo de teclado APG com busca por digitação, seleção simples, múltipla ou por checkbox com pais mistos, ramos preguiçosos que carregam na primeira abertura com um indicador de carregamento, altura animada, linhas-guia opcionais e ícones de pasta ou arquivo fornecidos pelo host.
Agente de IA com o servidor MCP do Marvelous UI: install_components({ slugs: ["tree-view"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).
none: browse only (a click on a branch toggles it). single: one selected item (aria-selected). multiple: click or Space toggles, Shift extends, Ctrl/Cmd+A selects all. checkbox: aria-checked on every item; checking a branch checks its descendants and parents show mixed.
expanded
string
Comma-separated ids of the branches open on load, or "all". Changing it later opens exactly those branches.
label
string
Accessible name of the tree (or put aria-label / aria-labelledby on the top <ul>).
guides
boolean
false
Vertical guide lines under each open branch; the line of the group holding the selection or focus is stronger.
icons
boolean
false
Draw a simple folder (open or closed) or file icon on items that have none. Not needed when you provide templates.
data-id
string
On an <li>: id used by value, expand(), collapse(), the expanded attribute and events. Without it, the id is the path of labels joined by / (e.g. src/components/Button.tsx).
data-expanded
boolean
On an <li>: open on load.
data-selected / data-checked
boolean
On an <li>: selected, or checked with all its descendants, on load (also read on items added later).
data-disabled
boolean
On an <li>: cannot be selected or checked, skipped by arrow keys.
data-lazy
boolean
On an <li>: a branch whose children are not there yet. The first opening shows a spinner and emits mv-load; append an <ul> of <li> (or <li> into its list) and the loading ends. Removing data-lazy without adding children shows the empty note.
data-icon
string
On an <li>: name of a <template data-icon> to use for its icon.
Properties
Name
Tipo
Description
value
string[]
Ids of the selected items (checked items in checkbox mode, fully checked branches included), in tree order. Assign an array or a comma-separated string to change it. Can be set before the element is defined.
strings
object
Override any default text: loading, empty, loadingItem ({label}), loadedItem ({ one, other } with {label} and {n}), emptyItem ({label}). Numbers and plurals follow the nearest lang (Intl). Can be set before the element is defined.
Methods
Name
Description
expand(id)
Open an item and all its ancestors so it becomes visible. Returns false for an unknown id.
collapse(id)
Close an item. Returns false for an unknown id.
expandAll()
Open every branch whose children are present (lazy branches stay closed, so nothing is fetched).
collapseAll()
Close every branch; focus moves up to the nearest visible item.
focus()
Focus the tree's current item (its single tab stop).
Events
Name
Description
mv-select
Selection or check changed. detail: { value, id, item, selected } or { value, id, item, checked } in checkbox mode.
mv-toggle
A branch opened or closed. detail: { id, item, expanded }.
mv-load
A data-lazy branch was opened for the first time. detail: { id, item }. Append its children to item.
Content structure
Name
Description
ul > li
One item: its text (or a single <span> / <a href>) is the label, a nested <ul> or <ol> holds its children.
template[data-icon]
Direct child of mv-tree-view: icon cloned into items. folder (and folder-open), file, or any name referenced by data-icon.
.mv-tree-view-icon
An element (or a leading <svg> / <img>) in an <li> used as that item's own icon.
.mv-tree-view-meta
Trailing text in an <li>, aligned to the end: size, status letter, badge.
CSS classes
Name
Description
mv-tree-view-row
Generated row of an item: chevron, checkbox, icon, label, meta.
mv-tree-view-label
The item's label (ellipsis when too long).
mv-tree-view-group
Generated on each nested list (role="group").
CSS variables
Name
Default
Description
--mv-tree-view-indent
1.25rem
Indentation per level.
--mv-tree-view-row-height
2rem
Minimum row height.
--mv-tree-view-padding
var(--mv-space-2)
Inline padding of rows.
--mv-tree-view-duration
var(--mv-duration-normal)
Base duration of the open and close animation.
Accessibility
APG Tree View: role tree on the top list, treeitem on each <li> (named by its row only, not its children), group on nested lists, aria-level, aria-expanded, aria-selected (aria-multiselectable in multiple mode) or aria-checked true/false/mixed in checkbox mode, aria-disabled, aria-busy while a branch loads. One tab stop (roving tabindex): Up/Down move through visible items, Right opens then goes to the first child, Left closes then goes to the parent (mirrored in RTL), Home/End, typeahead on labels, * opens all siblings, Enter/Space select or check (Enter also follows a link label), Shift+arrows and Shift+Space extend a multiple selection. Loading and loaded counts are announced in a polite live region. Collapsed children are hidden from assistive tech. Reduced motion: instant open, static spinner. Forced colors: system colors for selection, checkboxes, chevrons and guides.