DIAL File Manager

The DIAL File Manager (@epam/ai-dial-react-file-manager) is the React file browser of DIAL Chat, DIAL Admin, and the DIAL Quick Apps editor. It draws the folders tree, the file grid, and the upload, copy, move, rename, and delete flows. The host application loads the files and performs every operation. This reference is for frontend developers who embed it, and it assumes the UI Kit is installed.

Version scope

Everything below is checked against File Manager 0.4.0: its package.json, src/index.ts, src/components/FileManager/FileManager.tsx, and the README. File Manager 0.4.0 requires UI Kit 0.16, while the released DIAL web interfaces ship File Manager 0.3.x with UI Kit 0.15; see Versions in DIAL releases. The README's compatibility table still names UI Kit 0.14.0-dev.12, but the package.json peer range is ^0.16.0.

Install

npm install @epam/ai-dial-react-file-manager@0.4.0 @epam/ai-dial-ui-kit@0.16.0 ag-grid-community@35.2.1 ag-grid-react@35.2.1 react@19.2.5 react-dom@19.2.5

Peer dependency	Range	Why it is a peer
`@epam/ai-dial-ui-kit`	`^0.16.0`	The host renders with the same copy of the design system.
`ag-grid-community`, `ag-grid-react`	`^35.2.1`	AG Grid needs exactly one copy per host, or its module registration breaks.
`react`, `react-dom`	`^19.2.5`	—

@tabler/icons-react and mime-types install with the package. The package is published as an ES module only.

Load the stylesheets in this order:

import '@epam/ai-dial-ui-kit/styles.css';
import '@epam/ai-dial-react-file-manager/styles.css';

Since 0.4.0 the File Manager stylesheet no longer repeats the kit's utilities, so the kit's stylesheet is required.

How it works

DialFileManager manages navigation, selection, and its own dialogs, but never calls a backend. The host passes the files in items and handles each callback. When an operation completes, the host passes the updated items. Navigation and selection can be controlled (path, selectedPaths) or uncontrolled (defaultPath, defaultSelectedPaths).

import {
  DialFileManager,
  DialFileNodeType,
  type DialFile,
} from '@epam/ai-dial-react-file-manager';

const files: DialFile[] = [
  {
    id: 'documents',
    folderId: 'documents',
    name: 'Documents',
    path: '/Documents',
    nodeType: DialFileNodeType.FOLDER,
    items: [],
  },
];

export const Files = () => (
  <DialFileManager
    items={files}
    defaultPath="/Documents"
    onPathChange={(path) => console.info(path)}
  />
);

To back the File Manager with DIAL file storage, call the DIAL Core files API from the callbacks; see File management.

The DialFile model

Field	Required	Description
`path`	Yes	The full path of the file or folder
`name`	Yes	The display name
`folderId`	Yes	A folder identifier. The package's own fixtures set it to the identifier of the parent folder.
`nodeType`	Yes	`DialFileNodeType.FOLDER` or `DialFileNodeType.ITEM`
`items`	—	The children of a folder
`parentPath`	—	The path of the parent folder. A rename needs it.
`contentLength`, `contentType`	—	The size and MIME type of a file
`createdAt`, `updatedAt`	—	Timestamps, as strings
`permissions`	—	`DialFilePermission` values: `READ`, `WRITE`, or `SHARE`
`owner`, `author`	—	The owner of a shared file or folder, and its author
`bucket`, `url`, `resourceType`, `extension`, `id`, `nextToken`	—	Other storage metadata

Callbacks

Prop	Arguments	Called when
`onPathChange`	The new path	The user opens another folder
`onSelectedPathsChange`	A `Set` of paths	The selection changes
`onUploadFiles`	The files, the destination folder	The user uploads files
`onValidateUpload`	The files, the existing files, the destination folder	Before an upload. It returns a `FileUploadValidationResult`, directly or as a promise.
`onUploadValidationError`	A `FileUploadValidationError`	An upload is rejected. Without this callback, the File Manager shows its own error above the grid.
`onUploadArchive`	The `File`, its name, the destination folder	The user uploads an archive
`onCreateFolder`	The new item, the folder path, its identifier	The user creates a folder
`onCopyFiles`	The items, the destination folder	The user copies items
`onMoveToFiles`	The items, the source folder, the destination folder	The user moves items, or renames one
`onDeleteFiles`	The items, the source folder	The user deletes items
`onDownloadFiles`	The files	The user downloads items
`onUnshareFiles`	The files	The user chooses Unshare on items shared with them, which the host lists in `sharedWithMeIds`
`onRemoveFilesAccess`	The files	The user chooses Remove access on items they shared, which the host lists in `sharedByMePaths`
`onManagePermissions`, `onPreview`	The path	The user opens the permissions or a preview of an item
`onOpenInNewTab`	The file	The user opens a file in a new tab
`onSearchFiles`	The folder, the query	The user searches. The host returns the hits in `searchResults`.

A rename has no callback of its own. It calls onMoveToFiles with one item whose destinationUrl is the renamed path, and the parent folder as both the source and the destination. Without onMoveToFiles, a rename is discarded.

getItemActionRestriction(file, action) disables Move, Download, Rename, or Delete for a single item. It returns the reason to show beside the disabled action, or undefined to leave the action available.

Option groups

Prop	Configures
`treeOptions`	The folders panel: its header, extra buttons, storage tabs, expanded folders, and item icons
`gridOptions`	The grid: its columns, visible columns, selection mode, row icons, and action labels
`toolbarOptions`	The content header: the actions of the Add menu, the hidden-files toggle, and extra buttons
`sortOptions`	The Sort menu. Rows default to folders first, then name ascending; `{ sortable: false }` keeps the source order and hides the menu.
`navigationPanelOptions`	The breadcrumbs and the search field
`bulkActionsToolbarOptions`	The bar shown while items are selected
`deleteConfirmationOptions`, `unshareConfirmationOptions`	The confirmation dialogs
`destinationFolderPopupOptions`, `conflictResolutionPopupOptions`	The Copy and Move destination picker, and the name-conflict dialog

The storage tabs are the DialFileManagerTabs values All, MyFiles, Shared, Organization, and Review. useDialFileManagerTabs(tabLabels, initialTab) builds tabs from every value and keeps activeTab and handleTabChange for treeOptions. initialTab defaults to MyFiles, and the hook returns no tabs when tabLabels is omitted.

Other exports

Export	What it is
`DialFoldersTree`	The folders tree on its own, as a keyboard-accessible ARIA tree
`DialDestinationFolderPopup`	The Copy and Move folder picker
`DialFileManagerSortDropdown`	The Sort menu
`FileManagerProvider`, `useFileManagerContext`	The context provider `DialFileManager` runs on, and the hook that reads it
`DialFileNodeType`, `DialFilePermission`, `DialFileResourceType`, `DialFileManagerActions`, and other enums	The values the props and models use
`NAME_COLUMN`, `SIZE_COLUMN`, `UPDATED_AT_COLUMN`	The built-in grid columns

Moving from the UI Kit file manager

UI Kit 0.16.0 removed its legacy DialFileManager, DialFoldersTree, DialDestinationFolderPopup, their provider, hooks, enums, column constants, and the @epam/ai-dial-ui-kit/file-manager subpath. This package exports every one of these names, so the move is a change of import path. See the UI Kit legacy file manager migration guide.

Version scope​

Install​

How it works​

The DialFile model​

Callbacks​

Option groups​

Other exports​

Moving from the UI Kit file manager​

Further reading​