MDX components

FileTree

Render folder and file layouts in docs pages with FileTree, Folder, and File

What FileTree does

FileTree displays a directory layout as an expandable tree. Use it when a reader needs to see where files live in a project, such as a repository structure, a configuration folder, or the output of a generator. Each folder can be expanded or collapsed, and each entry can carry a short label that explains its purpose.

Use FileTree for physical layout. For the logical flow between parts of a system, use a Mermaid diagram instead.

Components

The file tree uses three components. Nest them to match the directory you want to show.

Component	Props	Purpose
`FileTree`	none	The outer container. Holds `Folder` and `File` elements.
`Folder`	`name` (string), `label?` (string), `open?` (boolean), `defaultOpen?` (boolean)	A directory. Can contain other `Folder` and `File` elements.
`File`	`name` (string), `label?` (string)	A file. Does not take children.

name is the text shown in the tree. label is an optional description shown next to the name. defaultOpen expands a folder when the page loads. open sets the folder's open state.

Basic example

The following MDX renders a small src directory. The src folder starts expanded, and the nested routes folder starts collapsed.

tsx

<FileTree>
  <Folder name="src" label="Source" defaultOpen>
    <Folder name="routes" label="HTTP routes">
      <File name="users.ts" label="User endpoints" />
    </Folder>
    <File name="index.ts" label="Entry point" />
  </Folder>
</FileTree>

Entries without a label show only their name:

tsx

<FileTree>
  <Folder name="docs" defaultOpen>
    <File name="README.md" />
    <File name="quickstart.md" />
  </Folder>
</FileTree>

Documenting a project layout

For a larger layout, add a label to each entry that a reader might not recognize from its name. Keep labels short, and open only the folders a reader needs first.

tsx

<FileTree>
  <Folder name="my-docs" label="Docs project" defaultOpen>
    <Folder name="content" label="Pages" defaultOpen>
      <Folder name="guides" label="Task guides">
        <File name="install.mdx" label="Installation steps" />
        <File name="configure.mdx" label="Configuration options" />
      </Folder>
      <File name="index.mdx" label="Home page" />
    </Folder>
    <Folder name="public" label="Static assets">
      <File name="logo.svg" label="Site logo" />
    </Folder>
    <File name="settings.json" label="Site configuration" />
  </Folder>
</FileTree>

Keep trees short:

A tree with more than about 20 visible entries is hard to scan. Split the layout across sections of the page, or show only the folders that the surrounding text discusses.

Writing rules

Every Folder and File needs a name. Entries without a name do not describe anything for the reader.
Nest Folder and File only inside FileTree or another Folder.
Show the layout your project uses. Do not show placeholder folders that the text never mentions.
Put the file tree in its own block, not inside a paragraph or list item.