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

Multiple Expand on click

Features

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

Usage

Builder

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

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

{#snippet treeItems(items: typeof tree['children'], depth: number = 0)}
  {#each items as item (item.id)}
    <div {...item.attrs}>
      <!-- Content here -->
      {#if item.children?.length}
        {@render treeItems(item.children, depth + 1)}
      {/if}
    </div>
  {/each}
{/snippet}

<div {...tree.root}>
  {@render treeItems(tree.children, 0)}
</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>;
};

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
```
```
(id: string) => boolean
```
Checks if an item is currently selected @param id - ID of the item to check
isExpanded
```
(id: string) => boolean
```
```
(id: string) => boolean
```
Checks if an item is currently expanded @param id - ID of the item to check

getItem

(id: string) => I | undefined

getItemId
```
(id: string) => string
```
```
(id: string) => string
```
Gets the DOM ID for a specific tree item @param id - ID of the item
getItemEl
```
(id: string) => HTMLElement | null
```
```
(id: string) => HTMLElement | null
```
Gets the DOM element for a specific tree item @param id - ID of the item
selectUntil
```
(id: string) => void
```
```
(id: string) => void
```
Selects all items between the last selected item and the specified item @param id - ID of the item to select until
getAllChildren
```
typeof Tree.getAllChildren
```
```
typeof Tree.getAllChildren
```
Helper function to get all child items in a tree or subtree @param treeOrChild - Tree or Child instance to get children from @param onlyVisible - If true, only returns visible (expanded) children

Properties

The properties returned from

new Tree()

collection
```
Collection<I>
```
```
Collection<I>
```
The items contained in the tree
multiple
```
Multiple
```
```
Multiple
```
If
true
true
, the user can select multiple items holding
Control
Control
/
Meta
Meta
or
Shift
Shift
expandOnClick
```
boolean
```
```
boolean
```
If
true
true
, groups (items with children) expand on click
typeaheadTimeout
```
number
```
```
number
```

typeahead

(
  letter: string,
) =>
  | {
      readonly child: Child<I>
      readonly value: string
      readonly typeahead: string
      readonly current: boolean
    }
  | undefined

expand
```
(id: string) => void
```
```
(id: string) => void
```
Expands a specific item @param id - ID of the item to expand
expandAll
```
() => void
```
```
() => void
```
Expands all items
collapse
```
(id: string) => void
```
```
(id: string) => void
```
Collapses a specific item @param id - ID of the item to collapse
collapseAll
```
() => void
```
```
() => void
```
Collapses all items
toggleExpand
```
(id: string) => void
```
```
(id: string) => void
```
Toggles the expanded state of an item @param id - ID of the item to toggle
select
```
(id: string) => void
```
```
(id: string) => void
```
Selects a specific item @param id - ID of the item to select
deselect
```
(id: string) => void
```
```
(id: string) => void
```
Deselects a specific item @param id - ID of the item to deselect
clearSelection
```
() => void
```
```
() => void
```
Clears all current selections
toggleSelect
```
(id: string) => void
```
```
(id: string) => void
```
Toggles the selected state of an item @param id - ID of the item to toggle
selectAll
```
() => void
```
```
() => void
```
Selects all visible items. If all items are already selected, clears the selection.
items
```
I[]
```
```
I[]
```
selected
```
FalseIfUndefined<Multiple>>
```
```
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>
```
```
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>[]
```
```
Child<I>[]
```
Array of Child instances representing the top-level items

Tree

Features

Usage

API Reference

Constructor Props

Methods

isSelected

isExpanded

getItem

getItemId

getItemEl

selectUntil

getAllChildren

Properties

collection

multiple

expandOnClick

typeaheadTimeout

typeahead

expand

expandAll

collapse

collapseAll

toggleExpand

select

deselect

clearSelection

toggleSelect

selectAll

items

selected

expanded

root

group

children