Skip to main content

Tree View

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

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

The builder store used to create the tree.

The builder store used to create a tree item.

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.