@halazv2/react-file-manager

Headless-ish React file browser with Finder-style spring-loaded folders, drag-and-drop, built-in icons, pins/recents, in-pane preview, and host-driven action menus. Bring your own data and API keep viewers (Foxit, OnlyOffice) and domain actions in the host.

Live demo: https://halazv2.github.io/react-file-manager/

Hover a folder while dragging it expands in the sidebar and opens in the browser after a short delay, just like macOS Finder.

Install

npm install @halazv2/react-file-manager

Peer dependencies: react and react-dom ≥ 18. Optional peer: pdfjs-dist ≥ 4 (PDF first-page thumbnails).

Styling (three layers)

Anything else (utility classes, extra BEM modifiers) is internal.

1. CSS variables on .rfm-root theming
2. aria-* / data-* state (aria-selected, aria-pressed, aria-expanded, aria-busy, data-theme, data-focused, data-drop-target, data-view, data-kind)
3. classNames slots + root className / style escape hatch

Import the published stylesheet (also pulled in by <FileManager />):

import "@halazv2/react-file-manager/styles.css";

Styles are unlayered, so they keep working beside a host Tailwind setup. Theme with CSS variables; restyle via classNames or selectors under .rfm-root.

.rfm-root {
  --rfm-accent: #0f766e;
  --rfm-selected: color-mix(in srgb, var(--rfm-accent) 12%, transparent);
}

.rfm-item[aria-selected="true"] {
  box-shadow: inset 0 0 0 1px var(--rfm-accent);
}

Tokens (defaults on :where(.rfm-root)): --rfm-accent, --rfm-accent-fg, --rfm-surface, --rfm-surface-sunken, --rfm-surface-hover, --rfm-selected, --rfm-text, --rfm-text-muted, --rfm-border, --rfm-danger, --rfm-radius, --rfm-radius-sm, --rfm-font, --rfm-font-size, --rfm-font-size-sm, --rfm-sidebar-width, --rfm-details-width, --rfm-row-height, --rfm-duration, --rfm-icon-accent, --rfm-icon-outline, --rfm-star, --rfm-shadow.

Pass theme="dark" or theme="light" to set data-theme on the root (omit for prefers-color-scheme).

Quick start

import { FileManager, moveNodes, type FileManagerNode } from "@halazv2/react-file-manager";
import { useState } from "react";

const initial: FileManagerNode[] = [
  {
    id: "docs",
    name: "Documents",
    kind: "folder",
    children: [{ id: "notes", name: "notes.txt", kind: "file", extension: "txt" }]
  }
];

export function App() {
  const [nodes, setNodes] = useState(initial);

  return (
    <div style={{ height: 560 }}>
      <FileManager
        nodes={nodes}
        storageKey="my-app-files"
        onMove={(ids, folderId) =>
          setNodes((current) => moveNodes(current, ids, folderId))
        }
        onOpenFile={(id) => console.log("open", id)}
        onGetPreviewUrl={(id) => `/api/files/${id}/preview`}
        onUpload={(files, folderId) => console.log(files, folderId)}
        onImport={(items, folderId) => console.log(items, folderId)}
        onCreateFolder={(parentId) => console.log("new folder in", parentId)}
        onCreateFile={(folderId) => console.log("new file in", folderId)}
        onRename={(id, name) => console.log("rename", id, name)}
        onDownloadFile={(id) => console.log("download", id)}
        getItemActions={(node) => [
          { id: "open", label: "Open", onClick: () => console.log(node.id) }
        ]}
        getBulkActions={(ids) => [
          { id: "merge", label: "Merge", onClick: () => console.log(ids) }
        ]}
      />
    </div>
  );
}

The component fills its parent. Give the parent a height.

What it includes

• Three-pane layout: sidebar, browser (list/cards), details
• Explorer/Finder-style list columns with sorting, prop-driven visibility, and pointer/keyboard resizing
• Built-in extension-aware file/folder icons with readable, color-coded extension badges
• Pins and recent folders (storageKey → localStorage)
• Breadcrumbs, multi-select, keyboard navigation
• Drag-and-drop move with spring-loaded folders
• OS file drops via onUpload; OS folder drops via onImport (keeps the folder tree)
• Virtualized list view for large folders
• In-pane preview: images always; PDF first page + text when pdfjs-dist is installed and onGetPreviewUrl is set
• Context / “more” menus via getItemActions; menus flip within the visible manager and scroll when necessary
• Bulk action bar via getBulkActions (Open / Delete defaults when callbacks exist)
• Rename, download file/folder, create file hooks
• Theme tokens (--rfm-accent, --rfm-selected, surfaces)

Host apps own document viewers, merge/split, RBAC, and domain modals wire them through callbacks and action getters.

Adapter example (reflow-style)

import type { FileManagerNode } from "@halazv2/react-file-manager";

type LibraryNode = {
  id: number;
  name: string;
  type: "folder" | "file";
  children?: LibraryNode[];
  extension?: string;
  file?: string;
};

export function mapLibraryToNodes(nodes: LibraryNode[]): FileManagerNode[] {
  return nodes.map((node) => ({
    id: String(node.id),
    name: node.name,
    kind: node.type === "folder" ? "folder" : "file",
    extension: node.extension,
    children: node.children ? mapLibraryToNodes(node.children) : undefined,
    meta: { file: node.file, sourceId: node.id }
  }));
}

Props

Every FileManagerProps field:

| Prop | Type | Notes | | --- | --- | --- | | nodes | FileManagerNode[] | Nested tree. Root is implied. | | folderId | string \| null | Controlled current folder. null is root. | | defaultFolderId | string \| null | Uncontrolled initial folder. | | onFolderChange | (id: string \| null) => void | Fired when the current folder changes. | | selectedIds | string[] | Controlled selection. | | defaultSelectedIds | string[] | Uncontrolled initial selection. | | onSelectionChange | (ids: string[]) => void | Fired when selection changes. | | view | "list" \| "cards" | Controlled browser view. | | defaultView | "list" \| "cards" | Uncontrolled initial view. Default list. | | onViewChange | (view) => void | Fired when the view toggle changes. | | searchQuery | string | Controlled search string. | | defaultSearchQuery | string | Uncontrolled initial search. | | onSearchChange | (query: string) => void | Fired as the search field changes. | | sortBy / defaultSortBy | FileManagerSortBy \| null | Controlled / initial sort field: name, size, kind, modifiedAt, or addedAt. Unset by default (null), preserving host order. | | onSortByChange | (sortBy: FileManagerSortBy \| null) => void | Fired from a header or Clear sort. null clears sorting. | | sortDirection / defaultSortDirection | "asc" \| "desc" | Controlled / initial sort direction. Default asc. | | onSortDirectionChange | (direction: "asc" \| "desc") => void | Fired when a header changes direction; selecting a new field or clearing resets to asc. | | sortComparator | (a: FileManagerNode, b: FileManagerNode) => number | Overrides built-in sorting. Headers are disabled; remove this prop to clear custom sorting. | | visibleColumns / defaultVisibleColumns | FileManagerColumn[] | Controlled / initial list columns. Defaults to all five; Name always appears first. | | onVisibleColumnsChange | (columns: FileManagerColumn[]) => void | For custom host controls using the controller's setVisibleColumns; the built-in browser has no visibility menu. | | columnWidths / defaultColumnWidths | FileManagerColumnWidths | Controlled / initial widths in CSS pixels. Name fills available space unless its width is specified. | | onColumnWidthsChange | (widths: FileManagerColumnWidths) => void | Fired when a column is resized. | | onOpenFolder | (id: string \| null) => void | Fired when a folder is opened (sidebar, double-click, Enter). | | rootLabel | string | Label for the implied root. Default "My files". | | className | string | Extra class on .rfm-root. | | style | CSSProperties | Inline style on .rfm-root. | | theme | "light" \| "dark" | Sets data-theme on the root. Omit for prefers-color-scheme. | | classNames | FileManagerClassNames | Slot classes: root, layout, sidebar, browser, details, item, treeRow, toolbar, search, menu, more, bulkBar, iconButton, viewToggle. | | isBusy | boolean | Shows the in-pane busy overlay (aria-busy). | | storageKey | string | Pins / recents localStorage key prefix. | | onMove | (ids, folderId) => void | Fired on drop. Use moveNodes for local state. | | onOpenFile | (id) => void | Double-click or Enter on a file. | | onGetPreviewUrl | (id) => string \| null \| Promise<…> | Preview URL for details pane. | | onUpload | (files, folderId) => void | File picker or OS file drop. Folder drops without onImport are flattened into files with webkitRelativePath. | | onImport | (items, folderId) => void | OS folder (and mixed) drops as a tree. Prefer this to create folders instead of documents. | | onCreateFolder | (parentId) => void | New folder action. | | onCreateFile | (folderId) => void | Optional “new document” entry. | | onRename | (id, name) => void | Inline rename (F2 or menu). Sets data-editing on the row. | | labels | Partial<FileManagerLabels> | Override UI copy (search, empty states, menus, live announcements). | | components | { Row?, Sidebar?, Browser?, DetailsPane? } | Replace layout pieces. Default remains batteries-included. | | onDownloadFile / onDownloadFolder | (id) => void | Download hooks. | | onDelete | (ids) => void | Delete / Backspace. | | getItemActions | (node) => FileManagerAction[] | Context / more menu items. | | getBulkActions | (ids) => FileManagerAction[] | Multi-select bar actions. Includes Download for selected files when onDownloadFile is set. | | getDetailRows | (node) => FileManagerDetailRow[] | Extra inspector rows after Type and Pages. | | renderDetailActions | (node) => ReactNode | Extra inspector buttons, kept with View and Download. | | canManage | boolean | Disables drag, drop, and mutations. Default true. | | enablePreview | boolean | Default true when onGetPreviewUrl is set. | | springLoadDelay | number | Hover delay in ms. Default 500. | | showDetails | boolean | Inspector pane. Default true. Collapses below ~900px via container queries. | | renderIcon | (node, size?) => ReactNode | Override built-in icons. | | renderPreview | (node) => ReactNode | Replace the details pane. | | renderActions | (node) => ReactNode | Extra per-item actions. | | showFilesInTree | boolean | List files under folders in the sidebar tree. Default true. | | treeRevealOnFileSelect | boolean | Selecting a file in the tree opens its parent folder in the browser. Default true. Set false for select-only. |

FileManagerNode:

type FileManagerNode = {
  id: string;
  name: string;
  kind: "folder" | "file";
  children?: FileManagerNode[];
  extension?: string;
  size?: number;
  modifiedAt?: string | number;
  addedAt?: string | number;
  meta?: Record<string, unknown>;
};

Columns and sorting

List view shows Name, Size, Kind, Date Modified, and Date Added. Sorting is unset by default, so the browser preserves the item order supplied by the host. Click a header to cycle through ascending → descending → unset. Selecting a different column starts ascending. Clear sort in the toolbar restores host order immediately, including in card view or when the sorted column is hidden. The active sorting applies to both list and card views, recursive search results, and spring-loaded folders. Without sorting, search results retain their original tree traversal order.

Configure which columns are shown with visibleColumns, or set their initial configuration with defaultVisibleColumns. Updating visibleColumns adds or removes headers and their corresponding row cells; the built-in browser has no column visibility menu. Name is always shown first and cannot be hidden. Name fills the available space by default, with a 180px minimum, while the other columns keep their default widths. Set columnWidths.name or defaultColumnWidths.name for a fixed Name width; resizing its header also sets a fixed width, starting from the rendered width. Omit the Name width from controlled columnWidths to restore flexible sizing. Drag a header divider to resize, or focus it and use Left/Right (10px steps), Home (minimum), or End (maximum). Explicit and resized widths range from 80px to 600px, with a 180px minimum for Name; flexible Name widths may grow beyond 600px. Wide listings scroll horizontally; headers remain visible during vertical scrolling. Column settings survive folder and view changes within the mounted manager.

Name, Size, and date sorting compare files and folders together; folders are not forced to the top. kind sorts files by extension (including node.extension overrides), with folder/file grouping in the chosen direction. Folder Size cells show child counts, not estimated bytes; Size sorting uses the host's size field (missing sizes count as zero). Dates accept ISO 8601 strings or Unix timestamps in milliseconds, display in the user's locale/time zone, and show — when missing or invalid. Unavailable dates sort after known dates in either direction. Supply real dates from your host data; the library does not generate them. The sidebar tree keeps its independent folders-first name ordering.

<FileManager
  nodes={nodes}
  defaultVisibleColumns={["name", "size", "kind", "modifiedAt"]}
  defaultColumnWidths={{ name: 300, modifiedAt: 180 }}
  defaultSortBy="modifiedAt"
  defaultSortDirection="desc"
/>

For host-managed settings, pass the controlled props together with their on...Change callbacks. Use sortBy={null} for controlled unsorted state, and handle null in onSortByChange when the user clears sorting. Omitting sortBy enables uncontrolled header sorting, optionally initialized with defaultSortBy. Hosts can persist those settings in their own store; storageKey continues to affect pins/recents only. Custom row components can read visibleColumns, columnWidths, and sorting state through the existing context.

Icons

FileTypeIcon, FolderTypeIcon, and defaultNodeIcon are public exports for host layouts. The built-in set recognizes 20+ extensions and shows each one as a readable, color-coded document badge; unknown extensions fall back to a labeled document glyph. Use renderIcon to replace these defaults for any node.

FileManagerDropItem (OS drops into onImport):

type FileManagerDropItem =
  | { kind: "file"; name: string; file: File }
  | { kind: "folder"; name: string; children: FileManagerDropItem[] };

FileManagerAction:

type FileManagerAction = {
  id: string;
  label: string;
  onClick: () => void | Promise<void>;
  disabled?: boolean;
  danger?: boolean;
  icon?: ReactNode;
};

Compound API

<FileManager /> stays batteries-included. For a custom shell, call useFileManager(props) (the same controller) and/or pass components:

import {
  FileManager,
  FileManagerBrowser,
  FileManagerDetailsPane,
  FileManagerRow,
  FileManagerSidebar,
  useFileManager,
} from "@halazv2/react-file-manager";

<FileManager
  nodes={nodes}
  components={{
    Row: FileManagerRow,
    Sidebar: FileManagerSidebar,
    Browser: FileManagerBrowser,
    DetailsPane: FileManagerDetailsPane,
  }}
/>

useFileManager must run under your own providers if you render the slot components yourself; the default <FileManager /> already provides context.

Tree helpers (listFolder, moveNodes, searchNodes, …) stay exported for host state.

Next.js / SSR

The package entry is a Client Component ("use client"). In the App Router, import FileManager from a client module.

storageKey pin/recent helpers no-op when window is undefined (SSR). They read localStorage only in the browser.

Known limitations

Card virtualization (list and cards after 40 items), host-callback errors, and pointer/touch internal moves are implemented. Remaining product gaps are listed under Roadmap.

Roadmap

Shipped in 0.3.0: icons, theming tokens, pins/recents, preview pipeline, action menus, bulk bar, rename/download/create-file hooks.

Still optional follow-ups:

• Upload widgets richer dropzones and progress UI
• Theming presets ready-made light/brand skins beyond CSS variables
• Mobile redesign touch-first layout and gestures
• iAfford adapter swap hard-coded LibraryFileManager for this package (after reflow validation)

Local demo

npm install
npm run dev

License

MIT