Direactree
A typed React component for showing, navigating, and editing directory trees. Selection, editing, drag and drop, search, permissions, and large-tree support are built in.
Direactree gives an application a familiar file-explorer experience without writing the tree rendering, path tracking, name editor, move rules, and tree updates yourself.
Why Direactree
Use Direactree wherever users look at or manage hierarchical data:
- File managers and IDE-style project explorers
- Content management systems and media libraries
- Category, menu, and organization editors
- Database-backed folder structures, including ones loaded on demand
- Read-only directory previews
The component does not talk to a backend. It takes a serializable tree and reports what the user asked for, so the same UI works with local React state, a REST API, or a state library.
How it works
Your TreeNode[]
↓
<Direactree />
↓
select / open / create / rename / delete / move / load
↓
useDireactree, your state library, or your API
↓
Updated TreeNode[]
- Pass a
TreeNode[]tostructure. - Direactree renders it and runs the editing interface.
- Callbacks describe what the user selected or tried to change.
- You apply the change, usually with one call from
useDireactree, and pass the new tree back.
Direactree never changes structure itself. If a callback returns a Promise, the tree shows the request as pending and waits. If the Promise rejects, the editor stays open and shows the error.
const tree = useDireactree(initialStructure);
<Direactree
structure={tree.structure}
onSave={tree.save}
onDelete={tree.remove}
onNodeMove={tree.move}
/>
Core features
Editing
- Create files and folders, rename, and delete, with an optional confirmation.
- Name checks while typing: blank names, forbidden characters, reserved names, length, and duplicates in the same folder.
- Drag nodes into folders, or before and after rows with
allowReorder. - Ready-made updates through
useDireactreeand pure helpers such asmoveNodeandapplySave. - Async callbacks with pending and error states.
Control
- Per-node permissions: lock a node, or turn off rename, delete, move, drop, or create for it.
- Controlled or uncontrolled selection, single or multiple.
- Controlled open folders with
expandedIds, to remember them between visits. - A ref handle:
revealNode,expandAll,collapseAll,select,focus.
Finding things
- Search that filters or highlights, opens the folders that hold a match, and marks it.
onNodeActivateon double click and Enter, to open a file.- Keyboard navigation, type-ahead, F2 to rename, Delete to delete.
Look
- Your own icons, badges, and labels per row, and a right-click menu with your own items.
plainorcardappearance,comfortableorcompactdensity, light, dark, or system theme.- Every color as a CSS token, state as data attributes, and
classNamesfor utility CSS. - Right-to-left layouts, reduced motion, and Windows high contrast.
Scale
- Lazy loading of folder contents with loading and retry rows.
- Virtualization: only the rows in view are rendered.
Every action is enabled only when you pass its handler. Read-only trees, partly editable trees, and full explorers use the same component.
Safety guarantees
Direactree refuses operations that would produce an invalid tree before your callback runs:
- A node cannot be moved into itself or a folder into one of its descendants.
- A file cannot receive children, and create cannot target a file.
- A drop that changes nothing is ignored.
- A move or a name that would put two items with the same name in one folder is refused.
- Actions turned off by permissions cannot be started from the toolbox, keyboard, menu, or drag and drop.
- Only one save, delete, or move runs at a time.
Continue with Getting started, play with the complete file explorer, or look up any prop and callback. Coming from an older version? See Upgrading.