Skip to content

UI Library for Design Engineers. Animated components and effects you can copy and paste into your apps. Free. Open Source.

5.2 KB
Raw Blame
---
title: File Tree
date: 2023-07-20
description: A component used to showcase the folder and file structure of a directory.
author: dillionverma
published: true
---

<ComponentPreview name="file-tree-demo" />

## Installation

<Tabs defaultValue="cli">

<TabsList>
  <TabsTrigger value="cli">CLI</TabsTrigger>
  <TabsTrigger value="manual">Manual</TabsTrigger>
</TabsList>
<TabsContent value="cli">

```bash
npx shadcn@latest add @magicui/file-tree
```

</TabsContent>

<TabsContent value="manual">

<Steps>

<Step>Copy and paste the following code into your project.</Step>

<ComponentSource name="file-tree" />

<Step>Update the import paths to match your project setup.</Step>

</Steps>

</TabsContent>

</Tabs>

## Usage

```tsx showLineNumbers
import { Tree } from "@/components/ui/file-tree"
import type { TreeViewElement } from "@/components/ui/file-tree"
```

```tsx showLineNumbers
const elements: TreeViewElement[] = [
  {
    id: "src",
    type: "folder",
    name: "src",
    children: [
      { id: "components", type: "folder", name: "components" },
      { id: "app", type: "folder", name: "app" },
      { id: "page", name: "page.tsx" },
      { id: "layout", name: "layout.tsx" },
    ],
  },
]

<Tree elements={elements} />
```

When you pass `elements` and omit `children`, the tree is rendered from data and siblings are sorted automatically using a folders-first alphabetical order. Use `sort="none"` to preserve the input order, or pass a custom comparator.

## Props

### Tree

| Prop                   | Type                                        | Default     | Description                                                           |
| ---------------------- | ------------------------------------------- | ----------- | --------------------------------------------------------------------- |
| `initialSelectedId`    | `string`                                    | `-`         | The ID of the initially selected item.                                |
| `indicator`            | `boolean`                                   | `true`      | Whether to show the tree indicator line.                              |
| `elements`             | `TreeViewElement[]`                         | `-`         | An array of tree view elements to render when `children` are omitted. |
| `initialExpandedItems` | `string[]`                                  | `-`         | An array of IDs for items that should be initially expanded.          |
| `openIcon`             | `React.ReactNode`                           | `-`         | Custom icon for open folders.                                         |
| `closeIcon`            | `React.ReactNode`                           | `-`         | Custom icon for closed folders.                                       |
| `sort`                 | `"default" \| "none" \| ((a, b) => number)` | `"default"` | Sorting mode used for data-driven trees rendered from `elements`.     |
| `dir`                  | `"rtl" \| "ltr"`                            | `"ltr"`     | The text direction of the tree.                                       |

### TreeViewElement

| Prop           | Type                 | Default | Description                                           |
| -------------- | -------------------- | ------- | ----------------------------------------------------- |
| `id`           | `string`             | `-`     | A unique identifier for the node.                     |
| `name`         | `string`             | `-`     | The label rendered for the node in data-driven mode.  |
| `type`         | `"file" \| "folder"` | `-`     | Explicit node type. Use `"folder"` for empty folders. |
| `isSelectable` | `boolean`            | `true`  | Whether the node can be selected.                     |
| `children`     | `TreeViewElement[]`  | `-`     | Child nodes for folders.                              |

### Folder

| Prop           | Type      | Default | Description                               |
| -------------- | --------- | ------- | ----------------------------------------- |
| `element`      | `string`  | `-`     | The name of the folder.                   |
| `value`        | `string`  | `-`     | The unique identifier for the folder.     |
| `isSelectable` | `boolean` | `true`  | Whether the folder can be selected.       |
| `isSelect`     | `boolean` | `-`     | Whether the folder is currently selected. |

### File

| Prop           | Type              | Default | Description                             |
| -------------- | ----------------- | ------- | --------------------------------------- |
| `value`        | `string`          | `-`     | The unique identifier for the file.     |
| `isSelectable` | `boolean`         | `true`  | Whether the file can be selected.       |
| `isSelect`     | `boolean`         | `-`     | Whether the file is currently selected. |
| `fileIcon`     | `React.ReactNode` | `-`     | Custom icon for the file.               |

### CollapseButton

| Prop        | Type                | Default | Description                                |
| ----------- | ------------------- | ------- | ------------------------------------------ |
| `elements`  | `TreeViewElement[]` | `-`     | An array of tree view elements to control. |
| `expandAll` | `boolean`           | `false` | Whether to expand all elements initially.  |