Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Icons 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
Show code
<app-tree-view aria-label="Files">
    <app-tree-node id="docs" label="Documents" icon="folder" badge="3" expanded="true">…</app-tree-node>
    <app-tree-node id="empty" label="Empty folder" icon="folder"></app-tree-node>
</app-tree-view>

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

Show code
<app-tree-view aria-label="Single" selection="Single" selected="s-cv">
    <app-tree-node id="s-docs" label="Documents" icon="folder" expanded="true">…</app-tree-node>
</app-tree-view>
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
Show code
<app-tree-view aria-label="Multiple" selection="Multiple" name="fileIds">
    <app-tree-node id="m-docs" label="Documents" icon="folder" expanded="true">…</app-tree-node>
</app-tree-view>

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
Show code
<app-tree-view aria-label="Pictures" load-url="/Components/AppTreeView?handler=Children">
    <app-tree-node id="pictures" label="Pictures" icon="folder" has-children="true"></app-tree-node>
</app-tree-view>
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
Show code
<app-tree-view load-url="/Components/AppTreeView/missing" error-text="Could not load this folder.">…</app-tree-view>

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
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.

none single multiple
  • Documents
    • CV.pdf
    • Offer letter.pdf
    • Contracts
      • NDA.pdf
      • MSA.pdf
  • Pictures
  • Empty folder
React, generated from the controls
<AppTreeView nodes={nodes} ariaLabel="Files" onSelect={(id, node) => …} />
Razor, the same props
<app-tree-view load-url="/Components/AppTreeView?handler=Children" aria-label="Files"> <app-tree-node id="docs" label="Documents" … /> … </app-tree-view>

10 props. The 3 most used come first.

Used on most screens 3 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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.