Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Multiple

Tick leaves and parents to choose several places in a hierarchy. A parent ticks every leaf under it.

Departments and teams
Tick Engineering to choose API and Web together. Data is disabled, so no tick reaches it. name posts one hidden value per chosen id.
  • Engineering
    • API
    • Web
    • Data
  • Operations
    • Support
    • Field teams
  • Finance
    • Billing
Show code
<app-tree-picker label="Departments" name="deptIds">
    <app-tree-node id="eng" label="Engineering" icon="folder-open" expanded="true">
        <app-tree-node id="eng-api" label="API" checked="true"></app-tree-node>
        <app-tree-node id="eng-web" label="Web"></app-tree-node>
        <app-tree-node id="eng-data" label="Data" disabled="true"></app-tree-node>
    </app-tree-node>
    <app-tree-node id="ops" label="Operations" icon="folder-open" expanded="true">
        <app-tree-node id="ops-support" label="Support"></app-tree-node>
        <app-tree-node id="ops-field" label="Field teams"></app-tree-node>
    </app-tree-node>
    <app-tree-node id="fin" label="Finance" icon="folder-open" expanded="true">
        <app-tree-node id="fin-billing" label="Billing"></app-tree-node>
    </app-tree-node>
</app-tree-picker>

Single

Choose exactly one leaf when the person picks one place in the hierarchy.

One team
selection="Single" takes one leaf. Parents cannot be chosen in this mode.
  • Engineering
    • API
    • Web
    • Data
  • Operations
    • Support
    • Field teams
  • Finance
    • Billing
Show code
<app-tree-picker label="Team" selection="Single">
    <app-tree-node id="eng" label="Engineering" icon="folder-open" expanded="true">
        <app-tree-node id="eng-api" label="API"></app-tree-node>
        <app-tree-node id="eng-web" label="Web"></app-tree-node>
        <app-tree-node id="eng-data" label="Data" disabled="true"></app-tree-node>
    </app-tree-node>
    <app-tree-node id="ops" label="Operations" icon="folder-open" expanded="true">
        <app-tree-node id="ops-support" label="Support"></app-tree-node>
        <app-tree-node id="ops-field" label="Field teams"></app-tree-node>
    </app-tree-node>
    <app-tree-node id="fin" label="Finance" icon="folder-open" expanded="true">
        <app-tree-node id="fin-billing" label="Billing"></app-tree-node>
    </app-tree-node>
</app-tree-picker>

With an error

Show why the field needs attention. The error marks the field invalid and sits under it.

A required field left empty
error names the problem, and the tree is marked invalid for assistive technology.
  • Engineering
    • API
    • Web
    • Data
  • Operations
    • Support
    • Field teams
  • Finance
    • Billing
Choose at least one team.
Show code
<app-tree-picker label="Departments" required="true" error="Choose at least one team.">…</app-tree-picker>

Pre-chosen

Start a form with leaves already ticked. The person can change them.

Defaults for a form
checked on a leaf starts it in Chosen once, when the field draws. Only leaves take checked: a parent is checked from its children.
  • Engineering
    • API
    • Web
    • Data
  • Operations
    • Support
    • Field teams
  • Finance
    • Billing
Show code
<app-tree-picker label="Departments">
    <app-tree-node id="eng" label="Engineering" icon="folder-open" expanded="true">
        <app-tree-node id="eng-api" label="API" checked="true"></app-tree-node>
        <app-tree-node id="eng-web" label="Web" checked="true"></app-tree-node>
        …
    </app-tree-node>
    …
</app-tree-picker>

Every option

Every value of every prop, one cell each.

nodes

hierarchy with parents
  • Engineering
    • API
    • Web
  • Operations
    • Support
flat list
  • Alpha
  • Bravo

selection

selection="Multiple" (default)
  • Engineering
    • API
    • Web
  • Operations
    • Support
selection="Single"
  • Engineering
    • API
    • Web
  • Operations
    • Support

checked

checked on a leaf (React: defaultValue={["eng-api"])
  • Engineering
    • API
    • Web
  • Operations
    • Support
checked with selection="Single" (React: value="eng-web")
  • Engineering
    • API
    • Web
  • Operations
    • Support

name

name: one hidden value per chosen id
  • Engineering
    • API
    • Web
  • Operations
    • Support

label, helper-text and error

label and helper-text
  • Engineering
    • API
    • Web
  • Operations
    • Support
Pick every team that needs access.
error
  • Engineering
    • API
    • Web
  • Operations
    • Support
Choose a team.

required and disabled

required
  • Engineering
    • API
    • Web
  • Operations
    • Support
disabled
  • Engineering
    • API
    • Web
  • Operations
    • Support

aria-label and id

aria-label: the accessible name when there is no visible label
  • Engineering
    • API
    • Web
  • Operations
    • Support
id: names the field
  • Engineering
    • API
    • Web
  • Operations
    • Support

Guidance

What to do, and what to avoid.

Use it when

  • A form needs one or many leaves of a hierarchy, such as departments and their teams.

Reach for something else when

  • A flat set of options. → AppSelect
  • A browsable hierarchy that is not a form field. → AppTreeView
  • Moving rows between two lists. → AppTransferList

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

multiple single
  • Engineering
    • Web
    • Operations
  • Sales
React, generated from the controls
<AppTreePicker nodes={nodes} name="deptIds" label="Departments" onChange={(value, { ids }) => save(value)} />
Razor, the same props
<app-tree-picker selection="Multiple" name="deptIds" label="Departments">
    <app-tree-node id="pg-eng" label="Engineering" expanded="true">
        <app-tree-node id="pg-web" label="Web"></app-tree-node>
        <app-tree-node id="pg-ops" label="Operations"></app-tree-node>
    </app-tree-node>
    <app-tree-node id="pg-sales" label="Sales"></app-tree-node>
</app-tree-picker>

18 props. The 2 most used come first.

Used on most screens 2 props

PropTypeDefaultDescription
selectiondefault multiple Single | Multiple multiple multiple ticks leaves and parents; single picks one leaf.
namedefault - string - Form field name: one hidden value per chosen id.

Less common 16 props

PropTypeDefaultDescription
labeldefault - string - The field label.
helper-textdefault - string - Help text under the field.
errordefault - string - An error message under the field; it also marks the field invalid.
requireddefault false bool false Marks the field as required.
disableddefault false bool false Disables the field.
iddefault from name string from name The id of the field.
aria-labeldefault the label string the label Accessible name of the tree, when there is no visible label.
chosen-titledefault Chosen string Chosen Heading of the chosen list.
clear-all-labeldefault Clear all string Clear all Label of the button that clears every choice.
empty-titledefault Nothing chosen yet string Nothing chosen yet Shown in the chosen list when nothing is chosen.
empty-textdefault Tick items in the tree. string Tick items in the tree. Text under the empty title.
no-match-textdefault No matches string No matches Shown when the search matches nothing; {query} is the search text.
remove-labeldefault Remove {name} string Remove {name} Remove button label; {name} is the chosen item.
search-labeldefault Search string Search Accessible name of the search box.
search-placeholderdefault Search string Search Placeholder of the search box.
selected-textdefault {n} selected string {n} selected Count line; {n} is the number chosen.

5 props.

Less common 5 props

PropTypeDefaultDescription
iddefault required string required Unique across the whole tree; selection and the posted values carry it.
labeldefault the id string the id The node's text.
expandeddefault false bool false Starts open.
checkeddefault false bool false Preselects a leaf. A parent cannot be checked.
disableddefault false bool false Lists the node but no click or key changes it, including through its parent.

Screen reader

15 notes
  • Follows the WAI-ARIA tree pattern: ArrowDown and ArrowUp move between rows, Home and End jump to the first and last row, and typing jumps to the next row whose label starts with the text typed.
  • ArrowRight opens a closed parent or moves to its first child; ArrowLeft closes an open parent or moves to its parent.
  • Only one row is in the tab order (a roving tabindex), so Tab reaches the tree once and the arrow keys move the focus between rows.
  • Enter and Space pick the focused row. In multiple selection they tick or untick it; in single selection they choose a leaf and do nothing on a parent. A disabled row ignores both keys.
  • In multiple selection the tree is multiselectable and each row reports aria-checked as true, false or mixed. A parent is mixed when some of its enabled leaves are chosen. Ticking a parent picks every enabled leaf under it, and ticking a parent whose leaves are all chosen clears them.
  • In single selection each leaf reports aria-selected; a parent never does.
  • Each row reports its depth, a parent reports aria-expanded, and a disabled row reports aria-disabled.
  • The visible checkboxes and expand chevrons are hidden from assistive technology and skipped by Tab; the row itself is the control.
  • The search box is named by the search label. ArrowDown and ArrowUp move from it into the tree. Typing matches labels ignoring case, keeps each match with its whole subtree and opens every parent of a match. When nothing matches, the no-match text with the query appears under the search box; it is not announced.
  • Backspace in an empty search box removes the last chosen item, in multiple selection only.
  • The Chosen panel lists each chosen leaf under its parent's label. Each item has a Remove button named with the remove label and the item's name. Clear all empties the selection and is disabled when nothing is chosen.
  • A polite status line under the Chosen panel announces the count, such as '2 selected', whenever the number of chosen items changes.
  • The tree is named by the visible label through aria-labelledby; ariaLabel replaces that name when it is set.
  • After Remove or Clear all, focus moves to the next Remove button, else the previous one, else the search box.
  • The error or helper text is linked to the field with aria-describedby.