Skip to content
Melt UI

Tree

A hierarchical list of items

  • index.svelte
  • lib
    • icons
      • JavaScript.svelte
      • Svelte.svelte
    • tree
      • Tree.svelte
      • TreeItem.svelte
  • routes
    • contents
      • +layout.svelte
      • +page.svelte

Props

Features

  • 🎹 Keyboard navigation
  • 🍃 Multi-selection mode
  • 🧠 Smart focus management
  • 🌳 Optional expand on click
  • 💬 Highlight items by typing them out (typeahead)

Usage

<script lang="ts">
  import { Tree } from "melt/builders";


  const items = [/* ... */]
  const tree = new Tree({ items });
</script>


<div {...tree.root}>
  {#each tree.items as item}
    <div {...item.root}>
      <button {...item.trigger}>
        {item.value}
      </button>
      {#if item.children}
        <div {...item.content}>
          {#each item.children as child}
            <div {...child.root}>
              <button {...child.trigger}>
                {child.value}
              </button>
            </div>
          {/each}
        </div>
      {/if}
    </div>
  {/each}
</div>

API Reference

Constructor Props

The props that are passed when calling 
new Tree()
    export type TreeProps<Item extends TreeItem, Multiple extends boolean = false> = {
      /**
       * If `true`, the user can select multiple items.
       * @default false
       */
      multiple?: MaybeGetter<Multiple | undefined>;
      /**
       * The currently selected item(s).
       * If `multiple` is `true`, this should be an `Iterable`.
       * Otherwise, it'll be a `string`.
       * @default undefined
       */
      selected?: MaybeMultiple<string, Multiple>;
      /**
       * Callback fired when selection changes
       * @param value - For multiple selection, a Set of selected IDs. For single selection, a single ID or undefined
       */
      onSelectedChange?: (value: Multiple extends true ? Set<string> : string | undefined) => void;
      /**
       * The currently expanded items
       *
       * @default undefined
       */
      expanded?: MaybeMultiple<string, true>;
      /**
       * Callback fired when expanded state changes
       * @param value - Set of expanded item IDs
       */
      onExpandedChange?: (value: Set<string>) => void;
      /**
       * If `true`, groups (items with children) expand on click.
       * @default true
       */
      expandOnClick?: MaybeGetter<boolean | undefined>;
      /**
       * The items contained in the tree.
       * @required
       */
      items: IterableProp<Item>;
      /**
       * How many time (in ms) the typeahead string is held before it is cleared
       * @default 500
       */
      typeaheadTimeout?: MaybeGetter<number | undefined>;
    };

Methods

The methods returned from 
new Tree()

  • isSelected 

    (id: string) => boolean
    Checks if an item is currently selected @param id - ID of the item to check

  • isExpanded 

    (id: string) => boolean
    Checks if an item is currently expanded @param id - ID of the item to check

  • expand 

    (id: string) => void
    Expands a specific item @param id - ID of the item to expand

  • collapse 

    (id: string) => void
    Collapses a specific item @param id - ID of the item to collapse

  • toggleExpand 

    (id: string) => void
    Toggles the expanded state of an item @param id - ID of the item to toggle

  • select 

    (id: string) => void
    Selects a specific item @param id - ID of the item to select

  • deselect 

    (id: string) => void
    Deselects a specific item @param id - ID of the item to deselect

  • clearSelection 

    () => void
    Clears all current selections

  • toggleSelect 

    (id: string) => void
    Toggles the selected state of an item @param id - ID of the item to toggle

  • selectAll 

    () => void
    Selects all visible items. If all items are already selected, clears the selection.

  • getItemId 

    (id: string) => string
    Gets the DOM ID for a specific tree item @param id - ID of the item

  • getItemEl 

    (id: string) => HTMLElement | null
    Gets the DOM element for a specific tree item @param id - ID of the item

  • selectUntil 

    (id: string) => void
    Selects all items between the last selected item and the specified item @param id - ID of the item to select until

Properties

The properties returned from 
new Tree()

  • collection 

    Collection<I>
    The items contained in the tree

  • multiple 

    Multiple
    If 
    true
    , the user can select multiple items holding 
    Control
    /
    Meta
    or 
    Shift

  • expandOnClick 

    boolean
    If 
    true
    , groups (items with children) expand on click

  • typeaheadTimeout 

    number

  • typeahead 

    (letter: string) => { child: Child<I>; value: string } | undefined

  • items 

    I[]

  • selected 

    FalseIfUndefined<Multiple>>
    Currently selected item(s) For multiple selection, returns a Set of IDs For single selection, returns a single ID or undefined

  • expanded 

    SvelteSet<string>
    Set of currently expanded item IDs

  • root 

    { role: string; "data-melt-tree-root": string }
    Gets ARIA attributes for the root tree element

  • group 

    { role: string; "data-melt-tree-group": string }
    ARIA attributes for group elements

  • children 

    Child<I>[]
    Array of Child instances representing the top-level items