FileTree

The FileTree component renders interactive hierarchical file trees with collapsible directories, file type icons, and optional annotations.

Basic example

Collapsed by default

Set defaultExpanded: false to start with all directories collapsed.

With annotations

Annotations appear as muted badges next to file names — useful for marking file status.

Properties

Property	Type	Default	Description
root	string	—	Optional root directory label
tree	FileNode[]	(required)	Array of file/directory nodes (min 1)
defaultExpanded	boolean	true	Whether directories start expanded

FileNode

Property	Type	Default	Description
name	string	(required)	File or directory name
annotation	string	—	Optional badge text (e.g. “new”)
children	FileNode[]	—	Child nodes (presence = directory)

Interaction events

When interactive: true is set, the file tree emits a filetree-select event when the user clicks a file or directory.

```ui:filetree
interactive: true
root: project
defaultExpanded: true
tree:
  - name: src
    children:
      - name: index.ts
      - name: utils.ts
  - name: package.json
```

Event kind: filetree-select

Payload field	Type	Description
path	string	Full path from root (e.g., project/src/index.ts).
type	"file" | "directory"	Whether the clicked item is a file or directory.
expanded	boolean | undefined	For directories, whether it was expanded or collapsed. Not present for files.

Accessibility

• The tree uses role="tree" on the root <ul> and role="treeitem" on each node.
• Directories include aria-expanded indicating their open/closed state.
• Keyboard navigation follows the WAI-ARIA Treeview pattern:
  • ArrowDown / ArrowUp — move focus between visible items
  • ArrowRight — expand directory, or move to first child
  • ArrowLeft — collapse directory, or move to parent
  • Enter / Space — toggle expand/collapse
  • Home / End — move to first/last visible item
• Annotations are included in each item’s aria-label.