J3W1 / DESIGN SYSTEM

Tree

Hierarchical navigation with explicit expansion and one roving tab stop.

stable · LIGHT DOM · 1.1.0

Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.

Standalone example ↗Copy file manifest Canonical JSON Vue gallery ↗Prepare an agent kit →

Live variants

default

Source
- App.vue
- styles.css
README.md

<j3w1-tree id="example-tree-default"><ul class="tree" role="tree" aria-label="Workspace files"><li role="treeitem" id="example-tree-default-tree-source" aria-expanded="true" tabindex="0" data-demo-focus-target=""><span data-tree-label="">Source<button type="button" tabindex="-1" data-tree-toggle="" aria-label="Toggle children">▸</button></span><ul role="group"><li role="treeitem" id="example-tree-default-tree-app" tabindex="-1" aria-selected="true"><span data-tree-label="">App.vue</span></li><li role="treeitem" id="example-tree-default-tree-styles" tabindex="-1" aria-selected="false"><span data-tree-label="">styles.css</span></li></ul></li><li role="treeitem" id="example-tree-default-tree-readme" tabindex="-1" aria-selected="false"><span data-tree-label="">README.md</span></li></ul></j3w1-tree>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@1.1.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/tree.css';
import '@j3w1/ui/register/tree';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@1.1.0 j3w1-ui copy tree --out ./vendor/j3w1/tree

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.
`selectedId`	`string`	Selected treeitem ID.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.
`expand`	`(id: string, expanded?: boolean): void`	Expand or collapse a parent by ID.

events

Name	Type / signature	Meaning
`j3w1-select`	`CustomEvent`	The user selected a visible enabled item.
`j3w1-toggle`	`CustomEvent`	A parent expanded or collapsed.

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Purpose

Navigate hierarchical items with explicit expansion and a single roving tab stop. Selection differs from expansion. Caller-supplied nodes represent identities; activation emits an event and never invents file access.

Anatomy

tree: Labelled tree with nested groups.
item: Named treeitems expose selection; parents also expose expansion.
children: A nested group hidden when the parent collapses.

States

State	Presentation	Non-colour channel
default	Visible named tree items.	Tree and group hierarchy.
selected	Selected fill, text and start indicator.	aria-selected.
expanded	Downward marker and visible children.	aria-expanded=true.
collapsed	Side marker and hidden children.	aria-expanded=false; children leave focus order.
focus-visible	Dashed ring on the item’s own label.	Roving native focus.
disabled	Disabled text at full opacity.	aria-disabled blocks selection.

Keyboard

Up / Down / Home / End: Move through visible items in source order.
Right / Left: Expand or enter a parent, collapse it or return to its parent. Mirror these keys in RTL.
Enter / Space: Select the focused enabled item.
Typing: Move to the next visible label starting with the character.

Accessibility

Implement the linked tree pattern. Only one visible item has tabindex=0. Labels exclude descendant text. Collapsing a parent of the focused item moves focus to that parent. Selection has a programmatic state and border indicator; disabled items do not activate.

Portability

Wrap labels and actions without changing source order. Use logical spacing in RTL. Preserve native target sizes at both densities; only bounded data regions may scroll horizontally. Use equivalent native semantics and approved roles; record any unsupported behavior as a mapping deviation. The host owns application data, persistence, permissions and services.

Non-examples

Unlabelled controls, color-only status, drag-only operations, hidden required instructions, stolen focus or an invented service success.