UI Ingredients v2.0.0-4

Tree View

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

Explorer
vite.config.ts
svelte.config.js
tsconfig.json
package.json

Anatomy

Usage

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

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

  let collection = createTreeCollection<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
canRename (node: T, indexPath: IndexPath) => boolean Function to determine if a node can be renamed
checkedValue string[] The controlled checked node value
collection TreeCollection<T> The tree collection data
defaultCheckedValue string[] The initial checked node value when rendered. Use when you don't need to control the checked node value.
defaultExpandedValue string[] The initial expanded node ids when rendered. Use when you don't need to control the expanded node value.
defaultFocusedValue string The initial focused node value when rendered. Use when you don't need to control the focused node value.
defaultSelectedValue string[] The initial selected node value when rendered. Use when you don't need to control the selected node value.
expandedValue string[] The controlled expanded node ids
expandOnClick true boolean Whether clicking on a branch should open it or not
focusedValue string The value 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.
loadChildren (details: LoadChildrenDetails<T>) => Promise<T[]> Function to load children for a node asynchronously. When provided, branches will wait for this promise to resolve before expanding.
onBeforeRename (details: RenameCompleteDetails) => boolean Called before a rename is completed. Return false to prevent the rename.
onCheckedChange (details: CheckedChangeDetails) => void Called when the checked value changes
onExpandedChange (details: ExpandedChangeDetails<T>) => void Called when the tree is opened or closed
onFocusChange (details: FocusChangeDetails<T>) => void Called when the focused node changes
onLoadChildrenComplete (details: LoadChildrenCompleteDetails<T>) => void Called when a node finishes loading children
onLoadChildrenError (details: LoadChildrenErrorDetails<T>) => void Called when loading children fails for one or more nodes
onRenameComplete (details: RenameCompleteDetails) => void Called when a node label rename is completed
onRenameStart (details: RenameStartDetails<T>) => void Called when a node starts being renamed
onSelectionChange (details: SelectionChangeDetails<T>) => void Called when the selection changes
scrollToIndexFn (details: ScrollToIndexDetails<T>) => void Function to scroll to a specific index. Useful for virtualized tree views.
selectedValue string[] The controlled selected node value
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-loading Present when loading
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-loading Present when loading
data-part branch-control
data-path The path of the item
data-renaming
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-loading Present when loading
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-loading Present when loading
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-loading Present when loading
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-renaming
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.
Previous Tour
Next Environment Provider