@aiquants/directory-tree

A high-performance React directory tree component with virtualization, file selection, and theming support.

Features

- 🚀 High Performance: Built with @aiquants/virtualscroll to handle large directory structures efficiently with O(log n) operations
- 🌀 Ultrafast Scrolling: Inherits adaptive tap scroll circle from VirtualScroll for navigating massive datasets
- 📁 File Selection: Interactive file selection with visual feedback and multiple selection modes
- 🎨 Theming: Customizable line colors with external theme control support
- ♿ Accessibility: Full keyboard navigation and screen reader support
- 📱 Responsive: Optimized for both desktop and mobile interfaces
- 🔧 TypeScript: Complete TypeScript support with comprehensive type definitions
- 💾 State Persistence: Automatic localStorage persistence for expansion states
- 🎯 Flexible Selection: Support for none, single, or multiple selection modes

Installation

``bash
npm install @aiquants/directory-tree


or

yarn add @aiquants/directory-tree

or

pnpm add @aiquants/directory-tree
`

Peer Dependencies

This package requires the following peer dependencies:

`bash
npm install react react-dom @aiquants/virtualscroll tailwind-variants tailwind-merge
`

Quick Start

`tsx
import React from 'react';
import { DirectoryTree, useDirectoryTreeState } from '@aiquants/directory-tree';
import { useTheme } from './hooks/useTheme'; // Your theme hook
import type { DirectoryEntry } from '@aiquants/directory-tree';

const sampleData: DirectoryEntry[] = [
{
name: 'src',
absolutePath: '/src',
relativePath: 'src',
children: [
{
name: 'components',
absolutePath: '/src/components',
relativePath: 'src/components',
children: [
{
name: 'App.tsx',
absolutePath: '/src/components/App.tsx',
relativePath: 'src/components/App.tsx',
children: null
}
]
}
]
}
];

export default function App() {
const { theme } = useTheme();
const {
toggle,
isExpanded,
expandMultiple,
collapseMultiple,
isPending
} = useDirectoryTreeState({
storageKey: 'my-directory-tree'
});

// Calculate line color based on theme
const lineColor = theme === "dark" ? "#4A5568" : "#A0AEC0";

const handleFileSelect = (absolutePath: string, relativePath: string) => {
console.log(File selected: ${absolutePath} (${relativePath}));
};

return (



);
}
`

API Reference

$3

The main component for rendering the directory tree.

#### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| entries | DirectoryEntry[] | Yes | Array of root directory entries to display |
| expansion | object | Yes | Configuration for tree expansion state and behavior |
| selection | object | Yes | Configuration for item selection |
| visual | object | No | Visual customization options |
| virtualScroll | DirectoryTreeVirtualScrollOptions | No | Pass-through options for the underlying VirtualScroll component |

#### Expansion Options (expansion)

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| toggle | (path: string, relativePath: string) => void | Yes | - | Function to toggle directory expansion state |
| isExpanded | (path: string) => boolean | Yes | - | Function to check if a directory is expanded |
| expandMultiple | (paths: string[]) => void | Yes | - | Function to expand multiple directories |
| collapseMultiple | (paths: string[]) => void | Yes | - | Function to collapse multiple directories |
| isPending | boolean | No | false | Whether the tree is in a pending state |
| alwaysExpanded | boolean | No | false | If true, all directories are always expanded |
| doubleClickAction | 'recursive' \| 'toggle' | No | 'recursive' | Action on double-clicking a directory |

#### Selection Options (selection)

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| onFileSelect | (absolutePath: string, relativePath: string) => void | Yes | - | Callback function triggered when a file is selected |
| selectedPath | string \| null | No | - | The currently selected file path |
| mode | 'none' \| 'single' \| 'multiple' | No | 'none' | Selection mode for items |
| selectedItems | Set | No | - | Set of paths for currently selected items |
| onSelectionChange | (path: string, isSelected: boolean) => void | No | - | Callback when item selection changes |

#### Visual Options (visual)

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| className | string | No | - | Optional CSS class name for the container |
| style | React.CSSProperties | No | - | Optional inline styles for the container |
| lineColor | string | No | '#A0AEC0' | The color of the tree lines |
| showTreeLines | boolean | No | true | Flag indicating whether to render tree connector lines |
| showExpandIcons | boolean | No | true | Flag indicating whether to render directory expand icons |
| showDirectoryIcons | boolean | No | true | Flag indicating whether to render directory type icons |
| showFileIcons | boolean | No | true | Flag indicating whether to render file type icons |
| iconOverrides | DirectoryTreeIconOverrides | No | - | Icon overrides applied globally |
| expandIconSize | number | No | - | Size of the expand icon |
| removeRootIndent | boolean | No | false | If true, removes the indentation and connector lines for root-level items |

$3

virtualScroll lets you customize the embedded @aiquants/virtualscroll instance without re-implementing list rendering. Every option is optional and mirrors the VirtualScroll API.

- overscanCount: Adjust how many items render beyond the viewport for smoother scrolling (default: 10).
- scrollBarOptions: Configure scrollbar appearance and behavior (width, thumb drag, track click, arrow buttons, tap scroll circle).
- behaviorOptions: Configure scrolling behavior (pointer drag, keyboard navigation, inertia, wheel speed).
- onScroll, onRangeChange, className, background, initialScrollIndex, initialScrollOffset: Hook into scroll lifecycle or provide bespoke styling.

Example:

`tsx
{...commonProps}
virtualScroll={{
overscanCount: 6,
behaviorOptions: {
enablePointerDrag: false,
},
scrollBarOptions: {
width: 14,
tapScrollCircleOptions: {
radius: 32
}
}
}}
/>;
`

$3

A hook for managing directory tree state with localStorage persistence.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| options | UseDirectoryTreeStateProps | Configuration options |

#### Options

| Option | Type | Description |
|--------|------|-------------|
| initialExpanded | Set | Initially expanded directories |
| storageKey | string | localStorage key for persistence (default: 'directory-tree-state') |

#### Returns

| Property | Type | Description |
|----------|------|-------------|
| expanded | Set | Currently expanded directories |
| toggle | (path: string, relativePath: string) => void | Toggle directory expansion |
| isExpanded | (path: string) => boolean | Check if directory is expanded |
| expand | (path: string) => void | Expand a directory |
| collapse | (path: string) => void | Collapse a directory |
| expandMultiple | (paths: string[]) => void | Expand multiple directories |
| collapseMultiple | (paths: string[]) => void | Collapse multiple directories |
| collapseAll | () => void | Collapse all directories |
| isPending | boolean | Whether a transition is pending |

$3

`typescript
type DirectoryEntry = {
name: string;
absolutePath: string;
relativePath: string;
children: DirectoryEntry[] | null;
};
`

Styling

The component uses Tailwind CSS for styling. Make sure you have Tailwind CSS configured in your project. The component supports both light and dark themes, but theme control is managed by the calling component.

$3

The lineColor prop allows you to control the tree line color based on your application's theme:

`tsx
import { useTheme } from './hooks/useTheme';

function MyComponent() {
const { theme } = useTheme();

// Calculate line color based on theme
const lineColor = theme === "dark" ? "#4A5568" : "#A0AEC0";

return (
// ... other props
visual={{
lineColor: lineColor
}}
/>
);
}
`

$3

You can customize the appearance by overriding the default Tailwind classes:

`tsx
visual={{
className: "custom-directory-tree",
style: { height: '400px' }
}}
// ... other props
/>
`

`css
.custom-directory-tree {
/ Your custom styles /
}
`

Advanced Usage

$3

The component is optimized for large datasets through virtualization:

`tsx
import { DirectoryTree } from '@aiquants/directory-tree';

// Handle thousands of entries efficiently
entries={largeDataset}
// ... other required props
visual={{
style: { height: '600px' }
}}
/>
`

$3

Enable multiple selection for batch operations:

`tsx
const [selectedItems, setSelectedItems] = useState(new Set());

const handleSelectionChange = (path: string, isSelected: boolean) => {
setSelectedItems(prev => {
const newSet = new Set(prev);
if (isSelected) {
newSet.add(path);
} else {
newSet.delete(path);
}
return newSet;
});
};

// ... other props
selection={{
mode: "multiple",
selectedItems: selectedItems,
onSelectionChange: handleSelectionChange,
onFileSelect: handleFileSelect // Required prop
}}
/>
`

$3

Control how directories behave on double-click:

`tsx
// ... other props
expansion={{
// ... required expansion props
doubleClickAction: "toggle" // Only toggle the clicked directory
// or
doubleClickAction: "recursive" // Expand/collapse all children (default)
}}
/>
`

$3

The useDirectoryTreeState hook automatically persists expansion state to localStorage:

`tsx
const { toggle, isExpanded, expandMultiple, collapseMultiple } = useDirectoryTreeState({
storageKey: 'myapp-directory-tree',
initialExpanded: new Set(['/src', '/docs'])
});
``

TypeScript Support

This package is written in TypeScript and provides comprehensive type definitions. All components and hooks are fully typed for the best development experience.

Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

License

MIT License - see the LICENSE file for details.

Author

- GitHub: fehde-k
- X (formerly Twitter): @fehdek

---

Made with ❤️ by the AIQuants team.