On this page
@addTagHelper *, Webority.Ui.RazorMultiple
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
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
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
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
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
error- Engineering
- API
- Web
- Operations
- Support
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.
18 props. The 2 most used come first.
Used on most screens 2 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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.