On this page
@addTagHelper *, Webority.Ui.RazorIcons and badges
Each node carries an icon, a label and an optional badge, and a disabled node takes no click or key.
Icons, badges and a disabled node
Open Documents: MSA.pdf is disabled, so no click or key changes it. Every node needs an id, unique across the whole tree. icon is a library icon name and badge-tone an app-badge tone. A node with nested nodes is a branch; a node with none is a leaf.
- Documents
- CV.pdf
- Offer letter.pdf
- MSA.pdf
- Empty folder
Selection
Choose one row when the person picks one thing, and tick a branch when they pick a group of files.
Single row
Click or press Enter or Space on a row. The selected row is marked.
- Documents
- CV.pdf
- Offer letter.pdf
Selected: s-cv
Multiple, with tri-state checkboxes
Tick Contracts: its children follow, except the disabled MSA.pdf, so Contracts shows mixed. A parent is checked when every child is, mixed when some are, and unchecked when none are. Ticking a parent ticks every loaded child except a disabled one. Space toggles the focused node.
- Documents
- CV.pdf
- Offer letter.pdf
- Contracts
- NDA.pdf
- MSA.pdf
Loading on demand
Load a branch only when someone opens it, so a large folder structure stays quick to draw.
Opening a branch
Open Pictures, then Holiday: each is fetched once, with a spinner while it loads. Mark a node with has-children and no nested nodes. The first time it opens, the tree GETs load-url with parentId added and expects a JSON array of nodes (id, label, icon, badge, badgeTone, children, hasChildren, checked, disabled).
- Pictures
A branch that fails
The branch closes and shows its error text; opening it again retries. A failure announces error-text and fires wui-tree:error.
- Broken folder
Every option
Every value of every prop, one cell each.
nodes
flat list- Alpha
- Bravo
- Charlie
branch that starts open- Documents
- CV.pdf
disabled node- Documents
- CV.pdf
- MSA.pdf
has children, loads on open- Pictures
icon and badge- Documents
badgeTone
badge-tone="neutral" (default)- neutral
badge-tone="primary"- primary
badge-tone="success"- success
badge-tone="warning"- warning
badge-tone="danger"- danger
badge-tone="info"- info
selection
selection="none" (default)- Documents
- CV.pdf
selection="single"- Documents
- CV.pdf
selection="multiple"- Documents
- CV.pdf
selected
selected="o-selected-cv"- Documents
- CV.pdf
checked
(default) leaves only- Alpha
- Bravo
- Charlie
checked parent- Documents
- Contracts
- NDA.pdf
- Contracts
one leaf (parents show mixed)- Documents
- CV.pdf
- Contracts
- NDA.pdf
onSelect
wui-tree:select: the id and node of the row activated- Documents
- CV.pdf
onCheck
wui-tree:check: every checked id, and the one toggled- Documents
- CV.pdf
loadChildren
loadChildren: React only, Razor uses load-url- Pictures
loadUrl
load-url: GET with parentId, answering a JSON array- Pictures
onLoadError
wui-tree:error: the id and message of a branch that failed- Broken folder
name
name: posts the checked or selected ids as form fields- Documents
- CV.pdf
loadingText
loading-text: announced while a branch loads- Pictures
errorText
error-text: announced when a branch fails- Broken folder
ariaLabel
aria-label: the accessible name of the tree- Alpha
id
id: names the wui-tree element- Alpha
className
class: extra class names on the tree- Alpha
ref
ref: React only, query the element by id- Alpha
Guidance
What to do, and what to avoid.
Use it when
- Data that nests to unknown depth: folders, categories, permissions.
- Choosing several items across levels with a parent that reflects its children.
- Large hierarchies where branches load when opened.
Reach for something else when
- A flat list of choices. → AppSelect, AppSelect mode="multiple", or AppRadioGroup
- Content that opens and closes in place. → AppAccordion
- Site or app navigation. → AppShell
- People by reporting line, drawn as an org chart. → AppOrgTree
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
10 props. The 3 most used come first.
Used on most screens 3 props
| Prop | Type | Default | Description |
|---|---|---|---|
| selectiondefault none | none | single | multiple | none | How rows are chosen: none, single (one selected row) or multiple (a tri-state checkbox per node). |
| selecteddefault - | string | - | Selected id (single mode, controlled). The tree shows this id whatever the user clicks until you change it; null selects nothing, and dropping the prop clears it. |
| load-urldefault - | string | - | Children endpoint used when loadChildren is not set: a GET with parentId=<id> added, answering a JSON array of nodes. |
Less common 7 props
| Prop | Type | Default | Description |
|---|---|---|---|
| namedefault - | string | - | Form field name: multiple posts one value per checked id, single posts the selected id. |
| loading-textdefault Loading | string | Loading | Announced while children load. |
| error-textdefault Could not load. Try again. | string | Could not load. Try again. | Announced when they fail. |
| aria-labeldefault - | string | - | Accessible name of the tree. |
| wui-tree:selectdefault - | event | - | A row was activated, by a click or by Enter or Space. |
| wui-tree:checkdefault - | event | - | A check was toggled; the detail carries every checked id. |
| wui-tree:errordefault - | event | - | Children could not be loaded; opening the node again retries. |
9 props.
Less common 9 props
| Prop | Type | Default | Description |
|---|---|---|---|
| iddefault required | string | required | The id of the tree element. |
| labeldefault the id | string | the id | The node's text. |
| icondefault - | string | - | A library icon name shown before the label. |
| badgedefault - | string | - | Short text shown after the label. |
| badge-tonedefault neutral | string | neutral | neutral / primary / success / warning / danger / info. |
| expandeddefault false | bool | false | Starts open. |
| checkeddefault false | bool | false | Starts checked (multiple selection). |
| disableddefault false | bool | false | Lists the node but no click or key changes it, including through its parent. |
| has-childrendefault false | bool | false | The node has children fetched from the tree's load-url the first time it opens. Ignored when nodes are nested inside it. |
Screen reader
3 notes- Follows the WAI-ARIA tree pattern: arrow keys move between rows and open or close branches, Home and End jump to the first and last row, typing jumps to a label, and Enter or Space activates a row.
- In multiple selection each row has a tri-state checkbox: a parent is checked, unchecked or mixed from its children.
- ariaLabel names the tree, and the loading and error text are announced while children load or fail.