Tree

Usage

Best Practices

• Treat key as the durable identifier. Do not derive it from display labels that may be translated or renamed.
• Use expandedKeys only when another surface needs to own expansion state; otherwise prefer defaultExpandedKeys.
• Keep permission-scope trees single-select and move actual grant assignment into TxTransfer, DataTable, or a detail panel.
• Use filterMethod for domain-specific search such as path aliases or hidden metadata; keep label search for simple trees.
• If you use leaf=false for lazy-looking placeholders, also provide a loading or empty child state in the surrounding UI. TxTree does not fetch children by itself.
• When replacing rows with the item slot, call toggleExpand() from the disclosure control and toggleSelect() from the selectable region instead of duplicating state logic.

API Reference

TxTree Props

TreeNode

TxTree Events

TxTree Slots

Admin Permission Scopes

TxTree is a good fit for resource scopes, permission domains, and organization hierarchies in admin pages. Pair it with TxSearchInput, pass the keyword into filterText, and let the selected key drive details, transfer lists, or audit timelines.

Exposed Methods

None. Control selection and expansion through props and emitted events.

Overview

• expandedKeys makes expansion controlled. The component still emits update:expandedKeys, but does not mutate internal expansion until the parent passes the new keys back.
• defaultExpandedKeys seeds uncontrolled expansion and can reset it later while expandedKeys is absent.
• Selection works the same way. The tree keeps its own selection unless modelValue is bound; defaultSelectedKeys seeds it. Before this, the selected set was derived from modelValue alone, so <TxTree :nodes="…" /> with no binding emitted update:modelValue into nothing and never lit a row — the tree looked clickable and was inert.
• A seed that changes while modelValue is bound is ignored, so it cannot become the fallback if the host later stops driving the selection.
• Hovering a selected row keeps its accent. :hover:not(.is-disabled) is (0,3,0) against .is-selected's (0,2,0), so the neutral hover fill used to replace the accent exactly while the pointer was on the row; the hover rule now excludes selected rows and they get their own, stronger, accent shade.
• Filtering does not mutate expansion state. It temporarily expands ancestors of matching nodes through effectiveExpanded while filterText is non-empty.
• The default filter checks node.label.toLowerCase().includes(query.toLowerCase()); custom filterMethod receives the trimmed original query.
• Selection is flat. checkable only changes the control UI; it does not implement parent/child tri-state or descendant cascading.
• disabled and node.disabled block selection, but caret expansion remains available for expandable nodes.
• The root uses role="tree" (with aria-multiselectable in multiple mode); each row wrapper is role="treeitem" carrying aria-level, aria-setsize, and aria-posinset (position within its sibling group), plus aria-expanded / aria-selected / aria-disabled as applicable, over a role="presentation" list. The item slot only replaces the inner row visuals, so these row semantics are preserved automatically.

Technologies

• Reviewed against packages/tuffex/packages/components/src/tree/src/TxTree.vue and types.ts.
• Existing tests cover expanded rendering, selection events, and the role="treeitem" set/position semantics (aria-setsize / aria-posinset over a presentational list); docs call out untested but source-visible behavior such as filtering expansion, controlled expansion, and non-cascading checkboxes.
• The permission orchestration example should keep TxTree responsible for scope selection only; assigning resources belongs in adjacent controls.
• Screenshot reference: .codex-screenshots/nexus-tree-permission-orchestration-demo-playwright-2026-05-28.png.
• Component source: packages/tuffex/packages/components/src/tree/src/TxTree.vue.
• Types: packages/tuffex/packages/components/src/tree/src/types.ts.
• Verified coverage: packages/tuffex/packages/components/src/tree/__tests__/tree.test.ts covers default-expanded child rendering, selection-value emission, and per-sibling aria-setsize / aria-posinset over a role="presentation" list.

Customization