Skip to main content

Tree View

A hierarchical list of nested items, where each item can have additional children elements.

View code

Project Structure

Features

Full keyboard functionality
Select individual items

Anatomy

Tree: The container in which the tree lies.
Item: The individual tree item element.
Group: An element where a subtree is nested.

API Reference

createTreeView

The builder function used to create the tree-view component.

Props

Prop	Default	Type / Description
`forceVisible`	`false`	`boolean` Whether or not to force the tree-view to always be visible. This is useful for custom transitions and animations using conditional blocks.
`defaultExpanded`	`[]`	`string[]` Which tree items are expanded by default.
`expanded`	-	`Writable<string[]>` Optionally pass a writable store to control the expanded items of the tree. If provided, this will override the value of the `defaultTree` prop. See Bring Your Own Store
`onExpandedChange`	-	`ChangeFn<string[]>` A callback called when the value of the `expanded` store should be changed. See Change Functions

Elements

Element	Description
`tree`	The builder store used to create the tree.
`item`	The builder store used to create a tree item.
`group`	The builder store used to create a tree group.

States

State	Description
`expanded`	The list of IDs of items that are expanded.
`selectedItem`	The currently selected item, or `null` if no item is selected.

Helpers

Helper	Description
`isExpanded`	A function that returns whether or not the item is expanded.
`isSelected`	A function that returns whether or not the item is selected.

tree

The tree list element.

Data Attributes

Data Attribute	Value
`[data-melt-id]`	A unique ID.

item

The list item.

Props

Prop	Default	Type / Description
`id` *	-	`string` The unique ID of the item.

Data Attributes

Data Attribute	Value
`[data-id]`	A unique ID.

Custom Events

Event	Value
`m-keydown`	`(e: ) => void`
`m-click`	`(e: ) => void`
`m-focus`	`(e: ) => void`

group

The list group item.

Props

Prop	Default	Type / Description
`id` *	-	`string` The unique ID of the group. Must match the ID of the item it belongs to.

Data Attributes

Data Attribute	Value
`[data-group-id]`	The unique ID of the list item the group belongs to.

Accessibility

Adheres to the Tree View WAI-ARIA design pattern

Key	Behavior
`Enter`	Selects the node.
`Space`	Selects the node.
`ArrowDown`	Moves focus to the next node that is focusable without opening or closing a node. If focus is on the last node, does nothing.
`ArrowUp`	Moves focus to the previous node that is focusable without opening or closing a node. If focus is on the first node, does nothing.
`ArrowRight`	When focus is on a closed node, opens the node; focus does not move. When focus is on a open node, moves focus to the first child node. When focus is on an end node, does nothing.
`ArrowLeft`	When focus is on an open node, closes the node. When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node. When focus is on a root node that is also either an end node or a closed node, does nothing.
`Home`	Moves focus to first node without opening or closing a node.
`End`	Moves focus to the last node that can be focused without expanding any nodes that are closed.
`A-Z`	Focus moves to the next node with a name that starts with the typed character. Search wraps to first node if a matching name is not found among the nodes that follow the focused node. Search ignores nodes that are descendants of closed nodes.

On This Page