npm package: @huongda-group/react-file-manager
Description: React File Manager is an open-source, user-friendly component designed to easily manage files and folders within applications. With smooth drag-and-drop functionality, responsive design, and efficient navigation, it simplifies file handling in any React p
Author: Saifullah Zubair
Latest version: 2.0.1

### [View demo](https://react-file-manager.huongda.dev/)

<p>
An open-source React.js package for easy integration of a file manager into applications. It provides a user-friendly interface for managing files and folders, including viewing, uploading, and deleting, with full UI and backend integration.
</p>

## ✨ Features

- **File & Folder Management**: View, upload, download, delete, copy, move, create, and rename files
  or folders seamlessly.
- **Grid & List View**: Switch between grid and list views to browse files in your preferred layout.
- **Navigation**: Use the breadcrumb trail and sidebar navigation pane for quick directory
  traversal.
- **Toolbar & Context Menu**: Access all common actions (upload, download, delete, copy, move,
  rename, etc.) via the toolbar or right-click. Utility actions like **Refresh, View Toggle, and Fullscreen** are always accessible for a consistent experience.
- **Multi-Selection**: Select multiple files and folders at once to perform bulk actions like
  delete, copy, move, or download.
- **Keyboard Shortcuts**: Quickly perform file operations like copy, paste, delete, and more using
  intuitive keyboard shortcuts.
- **Drag-and-Drop**: Move selected files and folders by dragging them to the desired directory,
  making file organization effortless.

## 🚀 Installation

To install `React File Manager`, use the following command:

```bash
npm i @huongda-group/react-file-manager
```

## 💻 Usage

Here’s a basic example of how to use the File Manager Component in your React application:

```jsx
import { useState } from "react";
import { FileManager } from "@huongda-group/react-file-manager";
import "@huongda-group/react-file-manager/dist/style.css";

function App() {
  const [files, setFiles] = useState([
    {
      name: "Documents",
      isDirectory: true, // Folder
      path: "/Documents", // Located in Root directory
      updatedAt: "2024-09-09T10:30:00Z", // Last updated time
    },
    {
      name: "Pictures",
      isDirectory: true,
      path: "/Pictures", // Located in Root directory as well
      updatedAt: "2024-09-09T11:00:00Z",
    },
    {
      name: "Pic.png",
      isDirectory: false, // File
      path: "/Pictures/Pic.png", // Located inside the "Pictures" folder
      updatedAt: "2024-09-08T16:45:00Z",
      size: 2048, // File size in bytes (example: 2 KB)
    },
  ]);

  return (
    <>
      <FileManager files={files} />
    </>
  );
}

export default App;
```

## 📂 File Structure

The `files` prop accepts an array of objects, where each object represents a file or folder. You can
customize the structure to meet your application needs. Each file or folder object follows the
structure detailed below:

```typescript
type File = {
  name: string;
  isDirectory: boolean;
  path: string;
  updatedAt?: string; // Optional: Last update timestamp in ISO 8601 format
  size?: number; // Optional: File size in bytes (only applicable for files)
  trash?: boolean; // Optional: Whether the file is in trash
};
```

## ⚙️ Props

| Name                     | Type                                                                                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `acceptedFileTypes`      | string                                                                                                                          | (Optional) A comma-separated list of allowed file extensions for uploading specific file types (e.g., `.txt, .png, .pdf`). If omitted, all file types are accepted.                                                                                                                                                                                                                                                                                                                                                             |
| `className`              | string                                                                                                                          | CSS class names to apply to the FileManager root element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `collapsibleNav`         | boolean                                                                                                                         | Enables a collapsible navigation pane on the left side. When `true`, a toggle will be shown to expand or collapse the navigation pane. `default: false`.                                                                                                                                                                                                                                                                                                                                                                        |
| `defaultNavExpanded`     | boolean                                                                                                                         | Sets the default expanded (`true`) or collapsed (`false`) state of the navigation pane when `collapsibleNav` is enabled. This only affects the initial render. `default: true`.                                                                                                                                                                                                                                                                                                                                                 |
| `enableFilePreview`      | boolean                                                                                                                         | A boolean flag indicating whether to use the default file previewer in the file manager `default: true`.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `filePreviewPath`        | string                                                                                                                          | The base URL for file previews e.g.`https://example.com`, file path will be appended automatically to it i.e. `https://example.com/yourFilePath`.                                                                                                                                                                                                                                                                                                                                                                               |
| `filePreviewComponent`   | (file: [File](#-file-structure)) => React.ReactNode                                                                             | (Optional) A callback function that provides a custom file preview. It receives the selected file as its argument and must return a valid React node, JSX element, or HTML. Use this prop to override the default file preview behavior. Example: [Custom Preview Usage](#custom-file-preview).                                                                                                                                                                                                                                 |
| `onUpload` | (file: File, onProgress?: (progress: number) => void) => Promise<any> | (Optional) A callback function triggered when a file is selected for upload. It receives the selected `file` object and an optional `onProgress` callback. It expects a Promise that resolves with the uploaded file details. You can call `onProgress(percentage)` (0-100) to update the upload progress bar in the UI.
| `files`                  | Array<[File](#-file-structure)>                                                                                                 | An array of file and folder objects representing the current directory structure. Each object includes `name`, `isDirectory`, and `path` properties.                                                                                                                                                                                                                                                                                                                                                                            |
| `fontFamily`             | string                                                                                                                          | The font family to be used throughout the component. Accepts any valid CSS font family (e.g., `'Arial, sans-serif'`, `'Roboto'`). You can customize the font styling to match your application's theme. `default: 'Nunito Sans, sans-serif'`.                                                                                                                                                                                                                                                                                   |
| `formatDate`             | (date: string \| Date) => string | (Optional) A custom function used to format file and folder modification dates. If omitted, the component falls back to its built-in formatter from `utils/formatDate`. Useful for adapting the date display to different locales or formats.
| `height`                 | string \| number                                                                                                                | The height of the component `default: 600px`. Can be a string (e.g., `'100%'`, `'10rem'`) or a number (in pixels).                                                                                                                                                                                                                                                                                                                                                                                                              |
| `initialPath`            | string                                                                                                                          | The path of the directory to be loaded initially e.g. `/Documents`. This should be the path of a folder which is included in `files` array. Default value is `""`                                                                                                                                                                                                                                                                                                                                                               |
| `isLoading`              | boolean                                                                                                                         | A boolean state indicating whether the application is currently performing an operation, such as creating, renaming, or deleting a file/folder. Displays a loading state if set `true`.                                                                                                                                                                                                                                                                                                                                         |
| `language` | string | A language code used for translations (e.g., `"en-US"`, `"fr-FR"`, `"tr-TR"`). Defaults to `"en-US"` for English. Allows the user to set the desired translation language manually. <br><br>**Available languages:** <br> 🇸🇦 `ar-SA` (Arabic, Saudi Arabia) <br> 🇩🇰 `da-DK` (Danish, Denmark) <br> 🇩🇪 `de-DE` (German, Germany) <br> 🇺🇸 `en-US` (English, United States) <br> 🇪🇸 `es-ES` (Spanish, Spain) <br> 🇮🇷 `fa-IR` (Persian, Iran) <br> 🇫🇮 `fi-FI` (Finnish, Finland) <br> 🇫🇷 `fr-FR` (French, France) <br> 🇮🇱 `he-IL` (Hebrew, Israel) <br> 🇮🇳 `hi-IN` (Hindi, India) <br> 🇮🇹 `it-IT` (Italian, Italy) <br> 🇯🇵 `ja-JP` (Japanese, Japan) <br> 🇰🇷 `ko-KR` (Korean, South Korea) <br> 🇳🇴 `nb-NO` (Norwegian, Norway) <br> 🇧🇷 `pt-BR` (Portuguese, Brazil) <br> 🇵🇹 `pt-PT` (Portuguese, Portugal) <br> 🇷🇺 `ru-RU` (Russian, Russia) <br> 🇸🇪 `sv-SE` (Swedish, Sweden) <br> 🇹🇷 `tr-TR` (Turkish, Turkey) <br> 🇺🇦 `uk-UA` (Ukrainian, Ukraine) <br> 🇵🇰 `ur-UR` (Urdu, Pakistan) <br> 🇻🇳 `vi-VN` (Vietnamese, Vietnam) <br> 🇨🇳 `zh-CN` (Chinese, Simplified) <br> 🇵🇱 `pl-PL` (Polish, Poland) |
| `layout`                 | "list" \| "grid"                                                                                                                | Specifies the default layout style for the file manager. Can be either "list" or "grid". Default value is "list".                                                                                                                                                                                                                                                                                                                                                                                                               |
| `maxFileSize`            | number                                                                                                                          | For limiting the maximum upload file size in bytes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `onCopy`                 | (files: Array<[File](#-file-structure)>) => void                                                                                | (Optional) A callback function triggered when one or more files or folders are copied providing copied files as an argument. Use this function to perform custom actions on copy event.                                                                                                                                                                                                                                                                                                                                         |
| `onCut`                  | (files: Array<[File](#-file-structure)>) => void                                                                                | (Optional) A callback function triggered when one or more files or folders are cut, providing the cut files as an argument. Use this function to perform custom actions on the cut event.                                                                                                                                                                                                                                                                                                                                       |
| `onCompress`             | (files: IFile[], name: string, callback: (result: { status: boolean; message: string }) => void) => void                                                                                | (Optional) A callback function triggered when "Compress" is selected. Receives selected files, suggested filename, and a callback to report status/message.                                                                                                                                                                                                                                                                                                                                                                                          |
| `onDecompress`           | (files: IFile[], destinationPath: string, callback: (result: { status: boolean; message: string }) => void) => void                                                                                | (Optional) A callback function triggered when "Decompress" is selected. Receives selected file, destination path, and a callback to report status/message. Only shows for single file selection.                                                                                                                                                                                                                                                                                                                                                       |
| `onCreateFolder`         | (name: string, parentFolder: [File](#-file-structure)) => void \| Promise<void>                                   | A callback function triggered when a new folder is created. Use this function to update the files state to include the new folder under the specified parent folder using create folder API call to your server. If it returns a Promise, the UI will wait for it to resolve before closing the input field. |
| `onDelete`               | (files: Array<[File](#-file-structure)>, trash: boolean) => void                                                                                | A callback function is triggered when one or more files or folders are deleted. The `trash` boolean indicates if it should be moved to trash or deleted permanently. |
| `onDownload`             | (files: Array<[File](#-file-structure)>) => void                                                                                | A callback function triggered when one or more files or folders are downloaded.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `onError`                | (error: { type: string, message: string }, file: [File](#-file-structure)) => void                                              | A callback function triggered whenever there is an error in the file manager. Where error is an object containing `type` ("upload", etc.) and a descriptive error `message`.                                                                                                                                                                                                                                                                                                                                                    |
| `onFileOpen`             | (file: [File](#-file-structure)) => void                                                                                        | A callback function triggered when a file or folder is opened.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `onFolderChange`         | (path: string) => void                                                                                                          | A callback function triggered when the active folder changes. Receives the full path of the current folder as a string parameter. Useful for tracking the active folder path.                                                                                                                                                                                                                                                                                                                                                   |
| `onFileUploaded`         | (response: { [key: string]: any }) => void                                                                                      | A callback function triggered after a file is successfully uploaded. Provides JSON `response` holding uploaded file details, use it to extract the uploaded file details and add it to the `files` state e.g. `setFiles((prev) => [...prev, JSON.parse(response)]);`                                                                                                                                                                                                                                                            |
| `onFileUploading`        | (file: [File](#-file-structure), parentFolder: [File](#-file-structure)) => { [key: string]: any }                              | A callback function triggered during the file upload process. You can also return an object with key-value pairs that will be appended to the `FormData` along with the file being uploaded. The object can contain any number of valid properties.                                                                                                                                                                                                                                                                             |
| `onLayoutChange`         | (layout: "list" \| "grid") => void                                                                                              | A callback function triggered when the layout of the file manager is changed.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `onPaste`                | (files: Array<[File](#-file-structure)>, destinationFolder: [File](#-file-structure), operationType: "copy" \| "move") => void  | A callback function triggered when when one or more files or folders are pasted into a new location. Depending on `operationType`, use this to either copy or move the `sourceItem` to the `destinationFolder`, updating the files state accordingly.                                                                                                                                                                                                                                                                           |
| `onRefresh`              | () => void                                                                                                                      | A callback function triggered when the file manager is refreshed. Use this to refresh the `files` state to reflect any changes or updates.                                                                                                                                                                                                                                                                                                                                                                                      |
| `onRename`               | (file: [File](#-file-structure), newName: string, parentPath?: string) => void \| Promise<void>                                        | A callback function triggered when a file or folder is renamed. Receives the file object, the new name, and optionally the parent directory path. If it returns a Promise, the UI will wait for it to resolve before closing the input field.                                                                                                                                                                                                                                                                                                                                                           |
| `onChmod`                | (files: Array<[File](#-file-structure)>, permissions: string) => void                                               | (Optional) A callback function triggered when the user changes file/folder permissions via the context menu. Receives the selected files and the new permissions as an octal string (e.g., "755", "644").                                                                                                                                                                                                                                                                                                |
| `onSelectionChange`      | (files: Array<[File](#-file-structure)>) => void                                                                                | (Optional) A callback triggered whenever a file or folder is **selected or deselected**. The function receives the updated array of selected files or folders, allowing you to handle selection-related actions such as displaying file details, enabling toolbar actions, or updating the UI.                                                                                                                                                                                                                                  |
| `permissions`            | { create?: boolean; upload?: boolean; move?: boolean; copy?: boolean; rename?: boolean; download?: boolean; delete?: boolean; chmod?: boolean; compress?: boolean; decompress?: boolean; } | An object that controls the availability of specific file management actions. Setting an action to `false` hides it from the toolbar, context menu, and any relevant UI. All actions default to `true` if not specified. This is useful for implementing role-based access control or restricting certain operations. Example: `{ create: false, delete: false }` disables folder creation and file deletion.                                                                                                                   |
| `primaryColor`           | string                                                                                                                          | The primary color for the component's theme. Accepts any valid CSS color format (e.g., `'blue'`, `'#E97451'`, `'rgb(52, 152, 219)'`). This color will be applied to buttons, highlights, and other key elements. `default: #6155b4`.                                                                                                                                                                                                                                                                                            |
| `style`                  | object                                                                                                                          | Inline styles applied to the FileManager root element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `theme`                  | "light" \| "dark"                                                                                                               | Specifies the theme of the file manager. Can be either "light" or "dark". `default: "dark"`.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `trash`                  | boolean                                                                                                                         | Enables the "Move to Trash" option in the delete confirmation modal. `default: false`.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `width`                  | string \| number                                                                                                                | The width of the component `default: 100%`. Can be a string (e.g., `'100%'`, `'10rem'`) or a number (in pixels).                                                                                                                                                                                                                                                                                                                                                                                                                |

## 🎨 Styling

You can customize the appearance of the file manager by using props or overriding CSS variables.

### Common Variables

The following CSS variables can be overridden in your global CSS to customize the look and feel. Use `!important` if necessary to override default or inline styles.

```css
:root {
  --fm-primary-color: #16a249 !important; /* Primary color */
  --fm-border-color: #16a249 !important; /* Border color */
}
```

| Variable                       | Description                                                                       | Default                 |
| ------------------------------ | --------------------------------------------------------------------------------- | ----------------------- |
| `--fm-primary-color`     | The primary color used for buttons and highlights. Maps to the `primaryColor` prop. | `#6155b4`               |
| `--fm-border-color`            | Color of the borders.                                                             | `#cfcfcf`               |
| `--fm-item-hover-bg-color`     | Background color when hovering over items.                                        | `rgba(0, 0, 0, 0.05)`   |
| `--fm-item-hover-color`        | Text color when hovering over items.                                              | `#000`                  |
| `--fm-font-size`               | Base font size.                                                                   | `16px`                  |
| `--fm-font-family`       | Font family used in the component. Maps to the `fontFamily` prop.                 | `Nunito Sans, sans-serif` |
| `--fm-bg-color`                | Background color of the file manager.                                             | `#ffffff`               |
| `--fm-secondary-bg-color`      | Secondary background (header, sidebar).                                           | `#f5f5f5`               |
| `--fm-tertiary-bg-color`       | Tertiary background (buttons).                                                    | `#f0f0f0`               |
| `--fm-text-color`              | Primary text color.                                                               | `#000000`               |
| `--fm-text-secondary-color`    | Secondary text color.                                                             | `#444444`               |
| `--fm-popover-bg-color`        | Background color for popovers/context menus.                                      | `#ffffff`               |
| `--fm-popover-border-color`    | Border color for popovers/context menus.                                          | `#c6c6c6`               |
| `--fm-popover-hover-bg-color`  | Hover background for popover items.                                               | `rgba(0, 0, 0, 0.07)`   |

### 🌙 Dark Theme

The file manager supports dark theme out of the box. To enable dark mode, you can use the `theme` prop:

```jsx
<FileManager files={files} theme="dark" />
```

Alternatively, you can add `data-theme="dark"` attribute to a container element:

```jsx
// Option 2: Add to a container element
<div data-theme="dark">
  <FileManager files={files} />
</div>
```

You can also toggle dark mode dynamically:

```jsx
function App() {
  const [isDark, setIsDark] = useState(false);

  return (
    <div data-theme={isDark ? "dark" : "light"}>
      <button onClick={() => setIsDark(!isDark)}>
        Toggle Theme
      </button>
      <FileManager files={files} />
    </div>
  );
}
```

The dark theme automatically adjusts all colors including backgrounds, text, borders, and hover states.

## ⌨️ Keyboard Shortcuts

| **Action**                     | **Shortcut**       |
| ------------------------------ | ------------------ |
| New Folder                     | `Alt + Shift + N`  |
| Upload Files                   | `CTRL + U`         |
| Cut                            | `CTRL + X`         |
| Copy                           | `CTRL + C`         |
| Paste                          | `CTRL + V`         |
| Rename                         | `F2`               |
| Download                       | `CTRL + D`         |
| Delete                         | `DEL`              |
| Select All Files               | `CTRL + A`         |
| Select Multiple Files          | `CTRL + Click`     |
| Select Range of Files          | `Shift + Click`    |
| Switch to List Layout          | `CTRL + Shift + 1` |
| Switch to Grid Layout          | `CTRL + Shift + 2` |
| Jump to First File in the List | `Home`             |
| Jump to Last File in the List  | `End`              |
| Refresh File List              | `F5` (also clears selection) |
| Clear Selection                | `Esc`              |

## 🛡️ Permissions

Control file management actions using the `permissions` prop (optional). Actions default to `true`
if not specified.

```jsx
<FileManager
  // Other props...
  permissions={{
    create: false, // Disable "Create Folder"
    delete: false, // Disable "Delete"
    download: true, // Enable "Download"
    copy: true,
    move: true,
    rename: true,
    upload: true,
    chmod: true,
    compress: true,
    decompress: true,
  }}
/>
```

## </> Custom File Preview

The `FileManager` component allows you to provide a custom file preview by passing the
`filePreviewComponent` prop. This is an optional callback function that receives the selected file
as an argument and must return a valid React node, JSX element, or HTML.

### Usage Example

```jsx
const CustomImagePreviewer = ({ file }) => {
  return <img src={`${file.path}`} alt={file.name} />;
};

<FileManager
  // Other props...
  filePreviewComponent={(file) => <CustomImagePreviewer file={file} />}
/>;
```

## 🧭 Handling Current Path

By default, the file manager starts in the root directory (`""`). You can override this by passing
an `initialPath` prop. For example, to start in `/Documents`:

```jsx
<FileManager initialPath="/Documents" />
```

### Controlled usage with `currentPath`

If you want to **track and control** the current folder, you can pair `initialPath` with the
`onFolderChange` callback. A common pattern is to keep the path in React state:

```jsx
import { useState } from "react";

function App() {
  const [currentPath, setCurrentPath] = useState("/Documents");

  return (
    <FileManager
      // other props...
      initialPath={currentPath}
      onFolderChange={setCurrentPath}
    />
  );
}
```

### Important notes

- `initialPath` is applied **only once** when the `files` state is first set.
- After that, folder changes are driven by `onFolderChange`.
- If you want to keep the path in sync with user navigation, use a controlled state (as shown
  above).

## ©️ License

React File Manager is [MIT Licensed](LICENSE).