Tree

Overview

Tree is generic over the node value type, with a non-generic context cascaded so the parts stay simple; every Item auto-wires aria-level / aria-setsize / aria-posinset from the composition. Selection is none / single / multiple (controlled via @bind-SelectedValue(s) or uncontrolled) and expansion is controlled via @bind-ExpandedValues. FocusMode is roving (default) or activedescendant for virtualized trees, and the tree can be authored as parts or driven from Items + an ItemTemplate.

Anatomy

@using Navius.Primitives.Components.Tree

<NaviusTree TValue="string" Label="Files">
    <NaviusTreeItem Value="@("node")">
        <NaviusTreeItemContent>
            <NaviusTreeItemIndicator />
            <NaviusTreeItemTrigger>node</NaviusTreeItemTrigger>
        </NaviusTreeItemContent>
        <NaviusTreeGroup>
            @* nested NaviusTreeItem children *@
        </NaviusTreeGroup>
    </NaviusTreeItem>
</NaviusTree>

Root

Prop	Type	Default	Description
`SelectionMode`	`string`	`"single"`	`"none"` \| `"single"` \| `"multiple"`.
`FocusMode`	`string`	`"roving"`	`"roving"` \| `"activedescendant"` (for virtualized trees).
`SelectedValue`	`TValue?`	-	Controlled single-select value. Pair with `SelectedValueChanged` (`@bind-SelectedValue`).
`SelectedValueChanged`	`EventCallback<TValue?>`	-	Fires when the controlled `SelectedValue` should change.
`DefaultSelectedValue`	`TValue?`	-	Initial single-select value when uncontrolled.
`SelectedValues`	`IReadOnlyList<TValue>?`	-	Controlled multi-select values. Pair with `SelectedValuesChanged` (`@bind-SelectedValues`).
`SelectedValuesChanged`	`EventCallback<IReadOnlyList<TValue>>`	-	Fires when the controlled `SelectedValues` should change.
`DefaultSelectedValues`	`IReadOnlyList<TValue>?`	-	Initial multi-select values when uncontrolled.
`ExpandedValues`	`IReadOnlyCollection<TValue>?`	-	Controlled expanded values. Pair with `ExpandedValuesChanged` (`@bind-ExpandedValues`).
`ExpandedValuesChanged`	`EventCallback<IReadOnlyCollection<TValue>>`	-	Fires when the controlled `ExpandedValues` should change.
`DefaultExpandedValues`	`IReadOnlyCollection<TValue>?`	-	Initial expanded values when uncontrolled.
`Disabled`	`bool`	`false`	Disables the whole tree (cascades to every node).
`Orientation`	`string`	`"vertical"`	Drives `data-orientation` for styling; the keyboard model stays vertical regardless.
`Dir`	`string?`	-	`"ltr"` \| `"rtl"`. Falls back to a cascaded direction provider; mirrors horizontal expand/collapse arrows under rtl.
`Label`	`string?`	-	Accessible name (`aria-label`).
`LabelledBy`	`string?`	-	Accessible name by reference (`aria-labelledby`).
`Items`	`IReadOnlyList<TreeNode<TValue>>?`	-	Data-driven mode: the hierarchical node set. When set, `ChildContent` is ignored.
`ItemTemplate`	`RenderFragment<TreeNode<TValue>>?`	-	Data-driven mode: renders each node’s row; the tree wires the group + recursion.
`OnSelectionChange`	`EventCallback<IReadOnlyList<TValue>>`	-	Fires with the full selection whenever it changes.
`OnExpandedChange`	`EventCallback<IReadOnlyList<TValue>>`	-	Fires with the full expanded set whenever it changes.
`ChildContent`	`RenderFragment?`	-	The tree’s items (markup mode).
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Item

Prop	Type	Default	Description
`Value`	`object`	required	The node’s unique identity (used for selection + expansion state).
`Disabled`	`bool`	`false`	Cannot be selected and is skipped by keyboard navigation.
`TextValue`	`string?`	rendered value	Overrides the text type-ahead matches against.
`ChildContent`	`RenderFragment?`	-	The node’s content (an ItemContent, plus an optional child Group).
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

ItemContent

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	The label-row content (an ItemIndicator + ItemTrigger + adornments).
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

ItemTrigger

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Trigger content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `span`.

ItemIndicator

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	The expand/collapse chevron.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `span`.

Group

Prop	Type	Default	Description
`KeepMounted`	`bool`	`false`	Keeps the subtree mounted (hidden) while collapsed instead of removing it from the DOM.
`ChildContent`	`RenderFragment?`	-	The nested Items.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Data attributes

Part	Attribute	Description
Root	`data-navius-tree`	Present on the tree.
Root	`data-orientation`	`"vertical"` \| `"horizontal"`
Root	`data-disabled`	Present when disabled.
Item	`data-navius-tree-item`	Present on every treeitem.
Item	`data-expanded`	Present on an expanded parent.
Item	`data-selected`	Present when selected (and selection is enabled).
Item	`data-disabled`	Present when disabled.
Item	`data-focused`	Present on the active node.
Item	`data-level`	The 1-based depth.
Item	`data-leaf`	Present on leaf nodes.
ItemContent	`data-level`	The 1-based depth.
ItemContent	`data-expanded`	Present when the node is an expanded parent.
ItemContent	`data-selected`	Present when selected.
ItemContent	`data-disabled`	Present when disabled.
ItemTrigger	`data-navius-tree-item-trigger`	Present on the trigger.
ItemTrigger	`data-expanded` / `data-selected` / `data-disabled`	Mirror the node state.
ItemIndicator	`data-navius-tree-item-indicator`	Present on the chevron.
ItemIndicator	`data-state`	`"expanded"` \| `"collapsed"`
ItemIndicator	`data-expanded`	Present when the node is an expanded parent.
ItemIndicator	`data-leaf`	Present on leaf nodes (nothing to expand).
Group	`data-navius-tree-group`	Present on the child container (`role=group`).
Group	`data-expanded`	Present while the group is open.
Group	`data-level`	The child depth.

Keyboard interactions

Key	Behavior
`ArrowDown` / `ArrowUp`	Moves through the visible rows in document order.
`ArrowRight`	Expands a collapsed parent, or moves to its first child (mirrored under rtl).
`ArrowLeft`	Collapses an expanded parent, or moves to its parent (mirrored under rtl).
`Home` / `End`	Moves to the first / last visible node.
`Enter` / `Space`	Selects the focused node (and toggles a parent’s expansion).
Type a character	Type-ahead: moves to the next node whose label starts with it.

ARIA mechanism

Implements the tree view WAI-ARIA APG pattern: role="tree" with a labelled name, treeitems with level/setsize/posinset, aria-expanded on parents only (never leaves), and aria-multiselectable in multiple mode. Give the tree a Label or LabelledBy. This behavior is covered by the Playwright browser test suite and gated by axe-core in CI.