File Explorer

The FileExplorer component is used to display file and folder hierarchies in a collapsible/expandable structure. It supports features like active states, links, nested levels, and tooltips.

Usage

import { FileExplorer } from '@harnessio/ui/components'

//...

const [expandedFolders, setExpandedFolders] = useState(['src']);

return (
  <FileExplorer.Root value={expandedFolders} onValueChange={setExpandedFolders}>
    <FileExplorer.FolderItem
      value="src"
      level={0}
      content={
        <FileExplorer.Root value={expandedFolders} onValueChange={setExpandedFolders}>
          <FileExplorer.FileItem level={1}>index.ts</FileExplorer.FileItem>
          <FileExplorer.FileItem level={1}>App.tsx</FileExplorer.FileItem>
          {/* Use CustomItem for custom non-interactive content */}
          <FileExplorer.CustomItem className="text-cn-3 pl-cn-lg">
            2 files total
          </FileExplorer.CustomItem>
        </FileExplorer.Root>
      }
    >
      src
    </FileExplorer.FolderItem>
  </FileExplorer.Root>
)

Basic File Explorer

Create a simple file explorer with folders and files. The explorer automatically handles expand/collapse interactions.

Nested Folders

You can nest folders within folders to create deep hierarchies.

With Active State

Highlight the currently active file or folder using the isActive prop.

With Links

Make files and folders navigable by providing the link prop.

With Tooltips

Add tooltips to files for additional information.

Active Folder

You can also highlight folders using the isActive prop.

Complex Example - Full Project Structure

This comprehensive example demonstrates all features of the FileExplorer component including:

• Multiple nested folder levels
• Active file highlighting
• Links for navigation
• Tooltips for additional context
• Mixed file and folder structures
• Click handlers for file selection

Custom Content with CustomItem

The FileExplorer.CustomItem component allows you to add custom, non-interactive content to your file explorer. Use it when you need to display informational content, placeholders, or any custom elements that don’t require file/folder interactive behavior.

API Reference

Root Component Props

Prop	Required	Default	Type
value	true		string[]
onValueChange	true		(value: string | string[]) => void
children	true		React.ReactNode

FolderItem Component Props

Prop	Required	Default	Type
children	true		React.ReactNode
level	true		number
value	false	''	string
isActive	false		boolean
content	false		React.ReactNode
link	false		string

FileItem Component Props

Prop	Required	Default	Type
children	true		React.ReactNode
level	true		number
isActive	false		boolean
link	false		string
onClick	false		() => void
tooltip	false		React.ReactNode

CustomItem Component Props

The FileExplorer.CustomItem component is a simple wrapper for custom, non-interactive content within the file explorer structure.

Prop	Required	Default	Type
children	true		React.ReactNode
className	false		string
ref	false		React.Ref<HTMLDivElement>

Use FileExplorer.CustomItem when you need full control over the content and styling without the standard file/folder behavior.

Best Practices

Level Numbering

• Folders: Start at level={0} for root folders, increment by 1 for each nesting level
• Files: Start at level={1} for files directly under root folders, increment by 1 for each nesting level

State Management

// Initialize with folders you want expanded by default
const [expanded, setExpanded] = useState(['src', 'components']);

// The Root component will handle the expand/collapse state
<Root value={expanded} onValueChange={setExpanded}>
  ...
</Root>

Performance Tips

• Use React.memo() for FileItem components if you have a large file tree
• Keep track of active file in state to avoid unnecessary re-renders
• Use the value prop on FolderItem to uniquely identify folders for proper accordion behavior