Trees Component (Interactive File Trees)

This guide explains how to build and use an interactive Trees component in Docusaurus, including native emoji mode and Iconify icon mode.

What This Adds

• Collapsible folder/file trees directly in .mdx docs
• Reusable components: Trees, Folder, and File
• Global MDX support (usable without local imports)
• Optional Iconify icons with extension-aware defaults (including .mdx)

Implementation in This Repo

The current implementation lives in:

• src/components/Trees/index.tsx
• src/components/Trees/Folder/index.tsx
• src/components/Trees/File/index.tsx
• src/components/Trees/utils/TreeItem.tsx
• src/components/Trees/styles.module.css
• src/theme/MDXComponents.tsx

Step 1: Install Iconify

Install Iconify for Mode 2 icon rendering:

npm install @iconify/react

Step 2: Register MDX Components Globally

Register Trees, Folder, and File in src/theme/MDXComponents.tsx:

import MDXComponents from '@theme-original/MDXComponents';
import type {MDXComponentsObject} from '@theme/MDXComponents';
import Trees from '@site/src/components/Trees';
import Folder from '@site/src/components/Trees/Folder';
import File from '@site/src/components/Trees/File';

const components: MDXComponentsObject = {
  ...MDXComponents,
  Trees,
  Folder,
  File,
};

export default components;

After this, all docs can use <Trees>, <Folder>, and <File> directly.

Step 3: Use in MDX

Mode 1: Native/Default

<Trees title="my-project">
  <Folder label="src" expanded>
    <File label="index.ts" />
    <File label="App.tsx" />
  </Folder>
  <File label="package.json" />
</Trees>

Visual Example:

mode-1-default

▼src

index.ts

App.tsx

package.json

Mode 2: Iconify Icons

<Trees title="my-project">
  <Folder label="src" icon="vscode-icons:folder-type-src" expanded>
    <File label="App.tsx" icon="vscode-icons:file-type-reactts" />
    <File label="styles.css" icon="vscode-icons:file-type-css" />
  </Folder>
  <File label="README.md" icon="vscode-icons:file-type-readme" />
</Trees>

Visual Example:

mode-2-iconify

▼src

App.tsx

styles.css

README.md

Mode 3: No Icon

<Trees title="minimal">
  <File label="notes.txt" icon={null} />
</Trees>

Visual Example:

mode-3-no-icon

▼notes

notes.txt

todo.md

Options Reference (With Examples)

<Trees> Options

• title (optional): Tree title shown at the top
• children (required): Nested Folder / File components

<Trees title="Project Files">
  <File label="README.md" />
</Trees>

<Folder> Options

• label (required): Folder name
• icon (optional): Iconify icon string, or null to hide icon
• iconSize (optional): Icon size in pixels
• badge (optional): Context label shown on the right
• expanded (optional): Initial expanded/collapsed state
• children (optional): Nested folders/files

<Trees title="Folder Options">
  <Folder
    label="src"
    icon="vscode-icons:folder-type-src"
    iconSize={22}
    badge="core"
    expanded
  >
    <File label="index.ts" />
  </Folder>

  <Folder label="hidden-icon-folder" icon={null}>
    <File label="notes.md" />
  </Folder>
</Trees>

<File> Options

• label (required): File name
• icon (optional): Iconify icon string, or null to hide icon
• iconSize (optional): Icon size in pixels
• badge (optional): Context label shown on the right

<Trees title="File Options">
  <File label="README.md" icon="vscode-icons:file-type-readme" iconSize={20} badge="docs" />
  <File label="package.json" badge="config" />
  <File label="no-icon.txt" icon={null} />
</Trees>

Behavior Notes

• level is internal and automatically managed (do not set manually)
• Explicit icon="..." overrides extension-based auto mapping
• icon={null} always disables icon rendering

Automatic File-Type Icon Mapping

This repo maps common extensions in TreeItem so file labels automatically get better icons when no explicit icon is set.

Examples:

• .mdx → vscode-icons:file-type-mdx
• .md → vscode-icons:file-type-markdown
• .json → vscode-icons:file-type-json
• .ts/.tsx → TypeScript icons

Unknown extensions fall back to vscode-icons:default-file.

Best Practices

• Keep tree depth reasonable for readability
• Use expanded only on key folders to reduce noise
• Use badges for context (e.g. badge="Config")
• Keep icon pack style consistent across a page

References

• Docux Trees Component
• Docux Columns Component
• Docusaurus MDX Component Scope
• Iconify Icon Sets