Tree View

A component for displaying hierarchical data in a tree structure, allowing users to expand and collapse branches.

Explorer

node_modules

src

vite.config.ts

svelte.config.js

tsconfig.json

package.json

Anatomy

Usage

<script lang="ts">
  import {type NodeProps, TreeView} from 'ui-ingredients';
  import {
    CheckSquareIcon,
    ChevronRightIcon,
    File01Icon,
    FolderIcon,
  } from '$lib/icons';

  interface Node {
    value: string;
    label: string;
    children?: Node[];
  }

  let collection = TreeView.collection<Node>({
    nodeToValue(node) {
      return node.value;
    },
    nodeToString(node) {
      return node.label;
    },
    rootNode: {
      value: '',
      label: '',
      children: [
        {
          value: 'node_modules',
          label: 'node_modules',
          children: [
            {
              value: 'node_modules/svelte',
              label: 'svelte',
            },
            {
              value: 'node_modules/ui-ingredients',
              label: 'ui-ingredients',
            },
          ],
        },
        {
          value: 'src',
          label: 'src',
          children: [
            {
              value: 'src/(home)',
              label: '(home)',
              children: [
                {
                  value: 'src/(home)/+page.svelte',
                  label: '+page.svelte',
                },
                {
                  value: 'src/(home)/hero.svelte',
                  label: 'hero.svelte',
                },
              ],
            },
            {
              value: 'src/+layout.svelte',
              label: '+layout.svelte',
            },
          ],
        },
        {
          value: 'vite.config.ts',
          label: 'vite.config.ts',
        },
        {
          value: 'svelte.config.js',
          label: 'svelte.config.js',
        },
        {
          value: 'package.json',
          label: 'package.json',
        },
      ],
    },
  });
</script>

<TreeView.Root {collection}>
  <TreeView.Label>Explorer</TreeView.Label>
  <TreeView.Tree>
    {#each collection.rootNode.children ?? [] as node, index}
      {@render TreeNode({
        node,
        indexPath: [index],
      })}
    {/each}
  </TreeView.Tree>
</TreeView.Root>

{#snippet TreeNode(props: NodeProps<Node>)}
  {#if props.node.children}
    <TreeView.Branch node={props.node} indexPath={props.indexPath}>
      <TreeView.BranchControl>
        <TreeView.BranchText>
          <FolderIcon />
          {props.node.label}
        </TreeView.BranchText>
        <TreeView.BranchIndicator>
          <ChevronRightIcon />
        </TreeView.BranchIndicator>
      </TreeView.BranchControl>
      <TreeView.BranchContent>
        <TreeView.BranchIndentGuide />

        {#each props.node.children as node, index}
          {@render TreeNode({node, indexPath: [...props.indexPath, index]})}
        {/each}
      </TreeView.BranchContent>
    </TreeView.Branch>
  {:else}
    <TreeView.Item node={props.node} indexPath={props.indexPath}>
      <TreeView.ItemIndicator>
        <CheckSquareIcon />
      </TreeView.ItemIndicator>
      <TreeView.ItemText>
        <File01Icon />
        {props.node.label}
      </TreeView.ItemText>
    </TreeView.Item>
  {/if}
{/snippet}

API Reference

Root

Prop	Default	Description
`collection`		`TreeCollection<T>` The tree collection data
`defaultExpandedValue`		`string[]` The initial expanded node ids when rendered. Use when you don't need to control the expanded node ids.
`defaultSelectedValue`		`string[]` The initial selected node ids when rendered. Use when you don't need to control the selected node ids.
`expandedValue`		`string[]` The controlled expanded node ids
`expandOnClick`	`true`	`boolean` Whether clicking on a branch should open it or not
`focusedValue`		`string` The id of the focused node
`id`		`string` The unique identifier of the machine.
`ids`		`{ root?: string; tree?: string; label?: string; node(value: string)?: string; }` The ids of the tree elements. Useful for composition.
`keepMounted`		`boolean` Whether to keep the component mounted after exit.
`lazyMount`		`boolean` Whether to enable lazy mounting.
`onExpandedChange`		`(details: ExpandedChangeDetails) => void` Called when the tree is opened or closed
`onFocusChange`		`(details: FocusChangeDetails) => void` Called when the focused node changes
`onSelectionChange`		`(details: SelectionChangeDetails) => void` Called when the selection changes
`selectedValue`		`string[]` The controlled selected node ids
`selectionMode`	`"single"`	`"single" \| "multiple"` Whether the tree supports multiple selection - "single": only one node can be selected - "multiple": multiple nodes can be selected
`typeahead`	`true`	`boolean` Whether the tree supports typeahead search
`asChild`		`Snippet` Render a different element.

Branch

Prop	Default	Description
`indexPath`		`number[]`
`node`		`any`
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-branch`
`data-depth`	The depth of the item
`data-disabled`	Present when disabled
`data-part`	branch
`data-path`	The path of the item
`data-scope`	tree-view
`data-selected`	Present when selected
`data-state`	"open" \| "closed"
`data-value`	The value of the item

BranchContent

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-depth`	The depth of the item
`data-part`	branch-content
`data-path`	The path of the item
`data-scope`	tree-view
`data-state`	"open" \| "closed"
`data-value`	The value of the item

BranchControl

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-depth`	The depth of the item
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-part`	branch-control
`data-path`	The path of the item
`data-scope`	tree-view
`data-selected`	Present when selected
`data-state`	"open" \| "closed"
`data-value`	The value of the item

BranchIndentGuide

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-depth`	The depth of the item
`data-part`	branch-indent-guide
`data-scope`	tree-view

BranchIndicator

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-part`	branch-indicator
`data-scope`	tree-view
`data-selected`	Present when selected
`data-state`	"open" \| "closed"

BranchText

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	branch-text
`data-scope`	tree-view
`data-state`	"open" \| "closed"

BranchTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	branch-trigger
`data-scope`	tree-view
`data-state`	"open" \| "closed"
`data-value`	The value of the item

Item

Prop	Default	Description
`indexPath`		`number[]`
`node`		`any`
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-depth`	The depth of the item
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-part`	item
`data-path`	The path of the item
`data-scope`	tree-view
`data-selected`	Present when selected
`data-value`	The value of the item

ItemIndicator

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-part`	item-indicator
`data-scope`	tree-view
`data-selected`	Present when selected

ItemText

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-part`	item-text
`data-scope`	tree-view
`data-selected`	Present when selected

Label

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Tree

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Accessibility

Keyboard Support

Key	Description
Tab	Moves focus to the tree view, placing the first tree view item in focus.
Enter + Space	Selects the item or branch node
ArrowDown	Moves focus to the next node
ArrowUp	Moves focus to the previous node
ArrowRight	When focus is on a closed branch node, opens the branch. When focus is on an open branch node, moves focus to the first item node.
ArrowLeft	When focus is on an open branch node, closes the node. When focus is on an item or branch node, moves focus to its parent branch node.
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 + A-Z	Focus moves to the next node with a name that starts with the typed character. The search logic ignores nodes that are descendants of closed branch.
*	Expands all sibling nodes that are at the same depth as the focused node.
Shift + ArrowDown	Moves focus to and toggles the selection state of the next node.
Shift + ArrowUp	Moves focus to and toggles the selection state of the previous node.
Ctrl + A	Selects all nodes in the tree. If all nodes are selected, unselects all nodes.