File manager React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

File manager is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import FileManager from @/components/ui/file-manager.

import { useState } from "react"
import { FileManager, type FileManagerItem, type FileManagerUpload } from "@/components/ui/file-manager"

export function Documents({ initial }: { initial: FileManagerItem[] }) {
  const [items, setItems] = useState(initial)
  const [uploads, setUploads] = useState<FileManagerUpload[]>([])

  return (
    <FileManager
      items={items}
      uploads={uploads}
      quota={{ used: 2.4 * 1024 ** 3, total: 10 * 1024 ** 3 }}
      locale="en-US"
      persistKey="crm:documents"
      labels={{ root: "Company files", search: "Search company files" }}
      onUpload={async (files, folderId) => {
        setUploads(files.map((file) => ({ id: file.name, name: file.name, size: file.size, progress: 0, status: "uploading", folderId })))
        const body = new FormData()
        files.forEach((file) => body.append("files", file))
        const saved: FileManagerItem[] = await (await fetch(`/api/files?folder=${folderId ?? ""}`, { method: "POST", body })).json()
        setItems((list) => [...list, ...saved])
        setUploads((list) => list.map((upload) => ({ ...upload, progress: 1, status: "done" })))
      }}
      onCreateFolder={async (name, parentId) => {
        const folder: FileManagerItem = await (await fetch("/api/folders", { method: "POST", body: JSON.stringify({ name, parentId }) })).json()
        setItems((list) => [...list, folder])
      }}
      onRename={async (item, name) => {
        await fetch(`/api/files/${item.id}`, { method: "PATCH", body: JSON.stringify({ name }) })
        setItems((list) => list.map((i) => (i.id === item.id ? { ...i, name } : i)))
      }}
      onMove={async (ids, parentId) => {
        await fetch("/api/files/move", { method: "POST", body: JSON.stringify({ ids, parentId }) })
        setItems((list) => list.map((i) => (ids.includes(i.id) ? { ...i, parentId } : i)))
      }}
      onDelete={async (ids) => {
        await fetch("/api/files", { method: "DELETE", body: JSON.stringify({ ids }) })
        setItems((list) => list.filter((i) => !ids.includes(i.id)))
      }}
    />
  )
}

Props

• items*default "[]"
  FileManagerItem[]

  The whole tree, flat: { id, kind: "folder" | "file", name, parentId (null at the root), size? (bytes), type? (mime), url?, thumbnailUrl?, modifiedAt?, modifiedBy?: { name, avatar? }, itemCount?, shared?, starred?, locked? }. The component filters by parentId; a parentId loop never hangs. Locked items cannot be renamed, moved or deleted; Move and Delete on a selection that holds some skip them. Tiles use content-visibility past 60 items; page from the server beyond about 2.000 files in one folder.

• rootLabeldefault ""
  string

  The root's name in the breadcrumb, the folder tree and search paths. Empty uses labels.root ("All files").

• quota
  { used: number; total: number }

  Bytes used and available: a thin bar with "2,4 GB of 10 GB" next to the breadcrumb, amber past 80% and red past 95%.

• uploadsdefault "[]"
  FileManagerUpload[]

  The uploads you are running: { id, name, size, progress (0 to 1), status: "uploading" | "done" | "error", error?, folderId }. They show in a floating panel at the bottom corner (collapsible, dismissible once nothing is running), next to the files the picker or a drop rejected.

• emptyState
  ReactNode

  Replaces the empty folder state (by default an icon, a line of text and New folder / Upload when those handlers exist).

• labels
  Partial<FileManagerLabels>

  Every string, English by default (DEFAULT_FILE_MANAGER_LABELS): root, region, folders, search, newFolder, folderName, create, cancel, upload, dropHere(folder), move, moveTo, moveHere, moveDescription(count, name), rename, download, delete, deleteTitle(count, name), deleteDescription, open, preview, select(name), selectAll, clearSelection, selected(count, formatted), items(count, formatted), results(count, formatted), name, modified, size, owner, type, sort, ascending, descending, view, grid, list, actions(name), sheetTitle, uploads, uploading(count, formatted), uploadsDone(count, formatted), uploadsFailed(count, formatted), uploadDone, uploadFailed, rejectedType, rejectedSize(max), collapse, expand, dismiss, storage, quota(used, total), empty, emptyDescription, noResults, noResultsDescription(query), clearSearch, loading, errorTitle, retry, moved(count, folder), renamed(name), deleted(count), created(name), failed, locked, shared, starred, folder, modifiedOn(when), dragging(count, name), pickedUp(count, name), dropped, dragCancelled, kinds (names per file kind).

• defaultViewdefault "grid"
  "grid" | "list"

  The first layout while uncontrolled: tiles with previews, or rows with Modified, Size and Owner columns. Phones start with the list until someone picks a view; search results are always a list.

• view
  "grid" | "list"

  The layout, controlled. Pair it with onViewChange.

• onViewChange
  (view: "grid" | "list") => void

  Called when the view switch in the toolbar changes.

• tileSizedefault "md"
  "sm" | "md" | "lg"

  The smallest tile width in the grid, 120 / 160 / 200px; the grid fits as many columns as it can. Below 512px of width (phones, side panels) it shows two columns.

• variantdefault "surface"
  "surface" | "plain"

  surface sits the manager in a raised panel; plain drops the panel, for a section card that already has one.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Selected tiles and rows, drop targets, checkboxes, the tree's current folder, progress bars and the Upload button of the empty state.

• colordefault ""
  string

  Any CSS color in place of the tone.

• showTreedefault true
  boolean

  The folder tree beside the files once the manager itself is 768px wide (a container query, so it also hides in a narrow panel on a wide screen). Its folders are drop targets too.

• showBreadcrumbdefault true
  boolean

  The path from the root to the open folder; every crumb is a drop target. Phones show a back link to the parent.

• loadingdefault false
  boolean

  Skeleton tiles or rows with the real shape while the first page loads.

• skeletonCountdefault 12
  number

  How many skeletons show while loading.

• errordefault ""
  ReactNode

  Replaces the files with an error state and its message; add onRetry for a Try again button.

• onRetry
  () => (void | Promise<unknown>)

  The error state's Try again button.

• defaultSearchdefault ""
  string

  A search to start with. Search looks through every folder, ignoring case and diacritics, and lists the results with their folder path.

• search
  string

  The search, controlled. Pair it with onSearchChange.

• onSearchChange
  (search: string) => void

  Called with the debounced query, and with "" when a folder is opened from the results.

• folderId
  string | null

  The open folder, controlled (null is the root). If it disappears from items, the nearest folder that still exists opens.

• defaultFolderIddefault "null"
  string | null

  The folder that opens first while uncontrolled (null is the root). The playground offers folders of the demo.

• onFolderChange
  (folderId: string | null) => void

  Called when a folder opens: a double-click, a crumb, the tree, Backspace.

• sort
  FileManagerSort

  The sort, controlled: { by: "name" | "modified" | "size" | "type", direction: "asc" | "desc" }. Folders always come first.

• defaultSortdefault "DEFAULT_FILE_MANAGER_SORT"
  FileManagerSort

  The first sort while uncontrolled: { by: "name", direction: "asc" }. Picking Modified or Size in the menu starts with the newest or largest.

• onSortChange
  (sort: FileManagerSort) => void

  Called from the sort menu and from the column headers of the list.

• selectedKeys
  string[]

  The selected ids, controlled. Pair it with onSelectedKeysChange.

• defaultSelectedKeysdefault "[]"
  string[]

  The ids selected at first while uncontrolled; with any selected the toolbar is the bulk bar.

• onSelectedKeysChange
  (keys: string[]) => void

  Called when the selection changes. Opening another folder clears it.

• persistKeydefault ""
  string

  Remembers the view and the sort in localStorage under this key ("<key>:view", "<key>:sort"). Empty remembers nothing.

• confirmDeletedefault true
  boolean

  Ask before deleting, in an alert dialog that names the file or the count. Off, Delete runs at once.

• previewImagesdefault true
  boolean

  Images open in the built-in lightbox with the folder's other images. Off, they go to onOpen like any other file.

• acceptdefault ""
  string

  What the upload picker offers, like the input's accept ("image/*,.pdf"). Dropped or pasted files outside it are listed as rejected in the uploads panel instead of reaching onUpload.

• maxFileSizedefault 0
  number

  The largest file in bytes; bigger ones are listed as rejected with the limit. 0 means no limit.

• uploadShortcutdefault ""
  string

  A key combo that opens the upload picker from anywhere on the page ("mod+u" notation). Empty binds nothing.

• localedefault ""
  string

  Formats sizes ("2,4 MB"), dates, counts and the sort order. Empty uses the UIProvider locale, then the browser's.

• now
  Date | number

  The reference time for "modified 5 min ago". Defaults to a live clock that ticks every minute; demos pin 24.09.2026 16:40.

• onOpen
  (item: FileManagerItem) => void

  Opens a file. Folders always open in place and images in the lightbox (while previewImages is on). Without it a file with a url opens in a new tab.

• onUpload
  (files: File[], folderId: string | null) => (void | Promise<unknown>)

  Turns on the Upload button, dropping files from the desktop and pasting them. folderId is the open folder, or the folder tile the files were dropped on. Report progress back through uploads.

• onCreateFolder
  (name: string, parentId: string | null) => (void | Promise<unknown>)

  Turns on New folder (a dialog, a sheet on phones). A rejected promise keeps the dialog open with its message, so you decide about duplicate names.

• onRename
  (item: FileManagerItem, name: string) => (void | Promise<unknown>)

  Turns on renaming in place. The field stays busy while the promise runs; a rejection shows its message under it and keeps it open.

• onMove
  (ids: string[], targetFolderId: string | null) => (void | Promise<unknown>)

  Turns on dragging onto folders, crumbs and tree nodes, and Move to (a dialog with the folder tree, a sheet on phones). Moves into the current folder, into itself or into a subfolder are refused before it runs.

• onDelete
  (ids: string[]) => (void | Promise<unknown>)

  Turns on Delete in the menus, the bulk bar and the Delete key. The confirmation stays loading while the promise runs.

• onDownload
  (items: FileManagerItem[]) => void

  Download for files and selections. Without it Download appears when every file has a url and saves them through links.

• getActions
  (item: FileManagerItem) => MenuEntry[]

  Extra menu entries per item (Share, Copy link, Star), between Download and Delete, in the W1 MenuEntry shape.

• classNames
  Partial<Record<"toolbar" | "breadcrumb" | "title" | "quota" | "body" | "tree" | "content" | "header" | "tile" | "row" | "select" | "icon" | "name" | "meta" | "actions" | "drop" | "uploads" | "empty" | "move" | "newFolder", string>>

  Extra classes for the parts. title is the phone's folder title, move and newFolder go on the dialogs' bodies, uploads on the floating panel.

• className
  string

  Extra classes for the root, merged last. Other props (id, aria-*, data-*, handlers) spread onto it.

Parts

FAQ

More React data display components