FileTree

Display hierarchical file structures with visual icons and descriptions

The FileTree component provides a beautiful way to display project file structures, directory hierarchies, and file organization in your documentation. It renders a static tree view with Lucide icons, optional descriptions, and badges in a clean code-block styled interface.

Basic Usage

Import the component and pass it a hierarchical structure of files and directories.

FileTree usage

import { FileTree } from "/snippets/tsdocs/FileTree.jsx"

const fileStructure = [
  {
    name: "src/",
    description: "Source code directory",
    children: [
      {
        name: "index.ts",
        description: "Main entry point"
      },
      {
        name: "components/",
        children: [
          { name: "Button.tsx", description: "Button component" },
          { name: "Card.tsx", description: "Card component" }
        ]
      }
    ]
  },
  {
    name: "package.json",
    description: "Package configuration",
    badge: { text: "Config", color: "blue" }
  }
];

<FileTree title="Project Structure" structure={fileStructure} />

Basic FileTree Example

Project Structure

src/Source code directory

index.tsMain entry point

components/

Button.tsxButton component

Card.tsxCard component

package.jsonPackage configurationConfig

Features

Visual Design

• Code block styling with rounded corners and syntax highlighting appearance
• Dark mode support with automatic theme switching
• Vertical guide lines for nested directory structures
• Consistent spacing and typography for optimal readability

File Icons

• Folder icons for directories (📁)
• File icons for individual files (📄)
• Icon customization via the getFileIcon function (extensible for different file types)

Metadata Support

• Descriptions provide context for files and directories
• Badges highlight important files with customizable colors
• Hierarchical structure supports unlimited nesting depth

Advanced Example

Here’s a comprehensive example showing a typical project structure with various file types and metadata:

Preview

Properties

structure · FileTreeItem[] · required

Hierarchical array of files and directories to display. Each item should have a name property.

title · string

Optional title displayed at the top of the file tree component

maxDepth · number · default: "10"

Maximum nesting depth to prevent infinite recursion in deeply nested structures

showIcons · boolean · default: "true"

Whether to display file and folder icons next to items

FileTreeItem Interface

Each item in the structure array should follow this interface:

interface FileTreeItem {
  name: string;           // File or directory name
  description?: string;   // Optional description shown next to the name
  badge?: FileTreeBadge; // Optional badge configuration
  children?: FileTreeItem[]; // Child items for directories
}

interface FileTreeBadge {
  text: string;          // Badge text content
  color?: string;        // Badge color (Mintlify Badge color prop)
}

FileTreeGroup

Use FileTreeGroup to organize multiple related file trees:

Preview

Best Practices

Use Descriptive Names

Choose clear, descriptive names for files and directories that immediately convey their purpose.

// ✅ Good
{ name: "user-authentication.ts", description: "Handles user login/logout logic" }

// ❌ Avoid
{ name: "util.ts", description: "Utility functions" }

Add Context with Descriptions

Use descriptions to provide additional context that helps users understand the purpose and contents of files/directories.

<FileTree
  title="API Structure"
  structure={[
    {
      name: "controllers/",
      description: "Request handlers that process incoming API calls"
    },
    {
      name: "models/",
      description: "Data models defining database schema structure"
    },
    {
      name: "middleware/",
      description: "Cross-cutting concerns like authentication and validation"
    }
  ]}
/>

Use Badges Strategically

Apply badges to highlight important files, configuration files, or items that need special attention.

<FileTree
  structure={[
    { name: "package.json", badge: { text: "Config", color: "blue" } },
    { name: "Dockerfile", badge: { text: "Docker", color: "green" } },
    { name: "README.md", badge: { text: "Docs", color: "purple" } },
    { name: "LICENSE", badge: { text: "Legal", color: "red" } }
  ]}
/>

Group Related Items

Organize file structures logically, grouping related functionality together and using FileTreeGroup for multiple related structures.

<FileTreeGroup title="Monorepo Structure">
  <FileTree title="Shared Packages" structure={sharedPackages} />
  <FileTree title="Frontend Apps" structure={frontendApps} />
  <FileTree title="Backend Services" structure={backendServices} />
</FileTreeGroup>

Keep Depth Reasonable

While FileTree supports unlimited nesting, limit depth to 4-5 levels for readability. Consider breaking very deep structures into separate documentation sections.

Styling and Theming

FileTree automatically adapts to Mintlify’s light and dark themes:

• Light mode: Light gray backgrounds with dark text
• Dark mode: Dark backgrounds with light text
• Code block styling: Consistent with other code elements in your documentation
• Vertical guide lines: Subtle visual indicators for nested structures
• Hover states: Clean interaction feedback
• Typography: Monospace font for file names, proportional font for descriptions

Troubleshooting

Component not found

If you see Cannot find module "/snippets/FileTree.jsx":

1. Ensure FileTree.jsx exists in your docs/snippets/ folder
2. Run mint-tsdocs to auto-install the component
3. Check that the import path is correct (should start with /snippets/)

Icons not displaying

If file/folder icons are not showing:

1. Verify that Mintlify’s Icon component is available
2. Check browser console for JavaScript errors
3. Ensure showIcons prop is not set to false

Structure not rendering

If the file tree doesn’t display correctly:

1. Verify that each item has a name property
2. Check that the structure prop is a valid array
3. Ensure proper JSON formatting in your MDX file

Styling issues

If the component doesn’t look right:

1. Ensure Tailwind CSS is properly loaded in your Mintlify site
2. Check that you’re using an up-to-date version of the component
3. Try refreshing the page to reload styles

Version History

v3.0.0

Initial release with hierarchical file structure visualization, Lucide icons, and code block styling

Future

• File type detection with specific icons for different extensions
• Expandable/collapsible directories
• File size and modification date display
• Copy file paths functionality

Related Components

JsonTree

Display JSON data structures with beautiful formatting

TypeTree

Display recursive type structures with expandable properties

Preview

Styled wrapper for component examples