Interface FileManagerProps

Props for the FileManager component.

Remarks

Requirement: Must be used inside a <FileCacheProvider> component (which itself must be inside a <HiyveProvider>) for automatic state management.

When used inside FileCacheProvider:

Files, folders, loading states, and callbacks are handled automatically
Only onFileOpen is required to handle file selection
Override props (files, folders, etc.) can be provided to customize behavior

When used standalone (without FileCacheProvider):

All data props (files, folders, currentPath, isLoading, userId) are required
All callbacks (onNavigate, onFileOpen, onRefresh) are required

Example

// Context-connected usage (recommended)
import { HiyveProvider } from '@hiyve/react';
import { FileManager, FileCacheProvider } from '@hiyve/react-collaboration';

function App() {
  return (
    <HiyveProvider generateRoomToken={getToken}>
      <FileCacheProvider>
        <FileManager
          onFileOpen={(file) => console.log('Opened:', file.fileName)}
          showToolbar
          showBreadcrumbs
        />
      </FileCacheProvider>
    </HiyveProvider>
  );
}

Example

// Filtered view (only shows specific types, flat view)
<FileManager
  filterFileTypes={['whiteboard']}
  onFileOpen={handleOpenWhiteboard}
  onSwitchToTab={handleTabSwitch}
/>

Example

// Standalone usage with explicit state management
<FileManager
  files={files}
  folders={folders}
  currentPath={currentPath}
  isLoading={isLoading}
  userId={userId}
  onNavigate={handleNavigate}
  onFileOpen={handleFileOpen}
  onRefresh={handleRefresh}
/>

interface FileManagerProps {
    availableTabs?: string[];
    colors?: Partial<FileManagerColors>;
    columns?: FileListColumn[];
    currentPath?: string;
    currentUserId?: string;
    customAction?: CustomToolbarAction | null;
    customContextActions?: CustomContextAction[];
    customFilters?: CustomToolbarFilter[];
    customViewers?: Partial<Record<string, CustomViewerRenderer>>;
    defaultFilterChip?: string;
    defaultViewMode?: FileManagerViewMode;
    enableDragDrop?: boolean;
    enableMarkers?: boolean;
    enableMultiSelect?: boolean;
    enableRegions?: boolean;
    enableSmartOpening?: boolean;
    fieldFormatters?: Partial<
        Record<FileListColumn, (file: FileEntry) => string>,
    >;
    fileNameFormatter?: (file: FileEntry) => string;
    files?: FileEntry[];
    filterChipPriority?: ResourceType[];
    filterChips?: { label: string; types?: ResourceType[] }[];
    filterFileTypes?: ResourceType[];
    folders?: FolderEntry[];
    getCommentCount?: (file: FileEntry) => number;
    icons?: Partial<FileManagerIcons>;
    isDownloading?: boolean;
    isLoading?: boolean;
    isRefreshing?: boolean;
    isRoomOwner?: boolean;
    isUploading?: boolean;
    isVisible?: boolean;
    labels?: Partial<FileManagerLabels>;
    onAddComment?: (fileId: string, content: string) => Promise<void>;
    onCreateFolder?: (name: string, parentPath: string) => Promise<void>;
    onDelete?: (files: FileEntry[]) => Promise<void>;
    onDeleteComment?: (fileId: string, commentId: string) => Promise<void>;
    onDeleteFolder?: (folder: FolderEntry) => Promise<void>;
    onDownload?: (files: FileEntry[]) => Promise<void>;
    onEditComment?: (
        fileId: string,
        commentId: string,
        content: string,
    ) => Promise<void>;
    onFetchFileTypes?: () => Promise<string[]>;
    onFileCountChange?: (count: number) => void;
    onFileEdit?: (file: FileEntry) => void;
    onFileOpen?: (file: FileEntry) => void;
    onGetAttendees?: () => Promise<{ userId: string; userName?: string }[]>;
    onGetComments?: (fileId: string) => Promise<FileComment[]>;
    onGetFileUrl?: (file: FileEntry) => Promise<string>;
    onGetMarkers?: (
        fileId: string,
    ) => {
        authorId?: string;
        authorName?: string;
        color?: string;
        content: string;
        createdAt?: string;
        editedAt?: string;
        id: string;
        time: number;
    }[];
    onGetRegions?: (
        fileId: string,
    ) => {
        channelIdx?: number;
        content: string;
        end: number;
        id: string;
        start: number;
    }[];
    onMarkerAdd?: (
        fileId: string,
        marker: {
            authorId?: string;
            authorName?: string;
            color?: string;
            content: string;
            createdAt?: string;
            editedAt?: string;
            id: string;
            time: number;
        },
    ) => void;
    onMarkerChange?: (
        fileId: string,
        marker: {
            authorId?: string;
            authorName?: string;
            color?: string;
            content: string;
            createdAt?: string;
            editedAt?: string;
            id: string;
            time: number;
        },
    ) => void;
    onMarkerDelete?: (fileId: string, markerId: string) => void;
    onMove?: (files: FileEntry[], newLocation: string) => Promise<void>;
    onNavigate?: (path: string) => void;
    onRefresh?: () => void;
    onRegionChange?: (
        fileId: string,
        region: {
            channelIdx?: number;
            content: string;
            end: number;
            id: string;
            start: number;
        },
    ) => void;
    onRegionDelete?: (fileId: string, regionId: string) => void;
    onRename?: (file: FileEntry, newName: string) => Promise<void>;
    onSelect?: (selection: { fileId: string; filename: string }) => void;
    onShare?: (files: FileEntry[], userIds: string[]) => Promise<void>;
    onSwitchToTab?: (tabName: string, file: FileEntry) => void;
    onUpload?: (file: File, location: string) => Promise<void>;
    onViewModeChange?: (mode: FileManagerViewMode) => void;
    refresh?: number;
    renderProps?: FileManagerRenderProps;
    renderShareUserList?: (
        props: {
            availableUsers: { userId: string; userName?: string }[];
            isDisabled: boolean;
            onToggleUser: (userId: string) => void;
            selectedUserIds: Set<string>;
        },
    ) => ReactNode;
    resourceTabMapping?: {
        add?: Record<string, string>;
        remove?: string[];
        replace?: Record<string, string>;
    };
    resourceViewerTypes?: {
        add?: string[];
        remove?: string[];
        replace?: string[];
    };
    roomName?: string;
    showBothOwnedAndShared?: boolean;
    showBreadcrumbs?: boolean;
    showOnlySharedFiles?: boolean;
    showToolbar?: boolean;
    sortStorageKey?: string;
    styles?: Partial<FileManagerStyles>;
    sx?: SxProps<Theme>;
    userId?: string;
    viewMode?: FileManagerViewMode;
}

Index

Properties

availableTabs? colors? columns? currentPath? currentUserId? customAction? customContextActions? customFilters? customViewers? defaultFilterChip? defaultViewMode? enableDragDrop? enableMarkers? enableMultiSelect? enableRegions? enableSmartOpening? fieldFormatters? fileNameFormatter? files? filterChipPriority? filterChips? filterFileTypes? folders? getCommentCount? icons? isDownloading? isLoading? isRefreshing? isRoomOwner? isUploading? isVisible? labels? onAddComment? onCreateFolder? onDelete? onDeleteComment? onDeleteFolder? onDownload? onEditComment? onFetchFileTypes? onFileCountChange? onFileEdit? onFileOpen? onGetAttendees? onGetComments? onGetFileUrl? onGetMarkers? onGetRegions? onMarkerAdd? onMarkerChange? onMarkerDelete? onMove? onNavigate? onRefresh? onRegionChange? onRegionDelete? onRename? onSelect? onShare? onSwitchToTab? onUpload? onViewModeChange? refresh? renderProps? renderShareUserList? resourceTabMapping? resourceViewerTypes? roomName? showBothOwnedAndShared? showBreadcrumbs? showOnlySharedFiles? showToolbar? sortStorageKey? styles? sx? userId? viewMode?

Properties

`Optional`availableTabs

availableTabs?: string[]

Available tabs for smart opening

`Optional`colors

colors?: Partial<FileManagerColors>

Custom colors for theming

`Optional`columns

columns?: FileListColumn[]

Columns to display in the file list

`Optional`currentPath

currentPath?: string

Current folder path (e.g., '/', '/Notes', '/Recordings/2024'). When inside FileCacheProvider, this is managed internally unless overridden.

`Optional`currentUserId

currentUserId?: string

Current user ID (used to determine edit permissions on markers)

`Optional`customAction

customAction?: CustomToolbarAction | null

Custom toolbar action

`Optional`customContextActions

customContextActions?: CustomContextAction[]

Custom context menu actions for files (appended after built-in actions)

`Optional`customFilters

customFilters?: CustomToolbarFilter[]

Custom filter dropdowns rendered in the toolbar alongside search and sort

`Optional`customViewers

customViewers?: Partial<Record<string, CustomViewerRenderer>>

Custom viewer renderers for specific resource types. These are passed to FileViewer for rendering custom file types.

`Optional`defaultFilterChip

defaultFilterChip?: string

Label of the filter chip to select by default. When provided, this chip is active on mount instead of "All".

`Optional`defaultViewMode

defaultViewMode?: FileManagerViewMode

Default view mode when uncontrolled

Default Value

'table'

`Optional`enableDragDrop

enableDragDrop?: boolean

Whether to enable drag-and-drop file moving

Default Value

true

`Optional`enableMarkers

enableMarkers?: boolean

Enable timeline markers for audio/video files

Default Value

false

`Optional`enableMultiSelect

enableMultiSelect?: boolean

Whether to enable multi-file selection

Default Value

true

`Optional`enableRegions

enableRegions?: boolean

Enable region creation and loop playback for audio/video files

Default Value

false

`Optional`enableSmartOpening

enableSmartOpening?: boolean

Enable smart opening (open whiteboards/notes in their respective tabs)

Default Value

false

`Optional`fieldFormatters

fieldFormatters?: Partial<Record<FileListColumn, (file: FileEntry) => string>>

Custom formatters for file list columns. Each key is a column name, and the value is a function that receives the file and returns a display string. The formatter's return value replaces the default cell text.

Example

<FileManager
  fieldFormatters={{
    roomName: (file) => roomAliasMap.get(file.roomName) || file.roomName,
    owner: (file) => userNameMap.get(file.userId) || file.userId,
  }}
/>

`Optional`fileNameFormatter

fileNameFormatter?: (file: FileEntry) => string

Custom file name formatter

`Optional`files

files?: FileEntry[]

Array of files in current folder. When inside FileCacheProvider, this is derived from context unless overridden.

`Optional`filterChipPriority

filterChipPriority?: ResourceType[]

Resource types to show first in auto-generated filter chips. Types not in this list appear after, sorted alphabetically. Only used when filterChips is not provided.

`Optional`filterChips

filterChips?: { label: string; types?: ResourceType[] }[]

Filter chip definitions to render between toolbar and content. When provided, a chip bar is shown allowing users to filter by resource type. The first chip is selected by default.

Example

<FileManager
  filterChips={[
    { label: 'All', types: undefined },
    { label: 'Whiteboards', types: ['whiteboard'] },
    { label: 'Notes', types: ['usernote', 'note'] },
  ]}
/>

`Optional`filterFileTypes

filterFileTypes?: ResourceType[]

Filter to specific file types (forces flat view)

`Optional`folders

folders?: FolderEntry[]

Array of subfolders in current folder. When inside FileCacheProvider, this is derived from context unless overridden.

`Optional`getCommentCount

getCommentCount?: (file: FileEntry) => number

Return the number of comments on a file (for badge display on file rows/cards). When provided, files with count > 0 show a comment icon.

`Optional`icons

icons?: Partial<FileManagerIcons>

Custom icons

`Optional`isDownloading

isDownloading?: boolean

Whether download is in progress (managed internally when inside FileCacheProvider)

`Optional`isLoading

isLoading?: boolean

Whether files are currently loading. When inside FileCacheProvider, this is derived from context unless overridden.

`Optional`isRefreshing

isRefreshing?: boolean

Whether refresh is in progress (managed internally when inside FileCacheProvider)

`Optional`isRoomOwner

isRoomOwner?: boolean

Whether current user is room owner (derived from context when inside FileCacheProvider)

`Optional`isUploading

isUploading?: boolean

Whether upload is in progress (managed internally when inside FileCacheProvider)

`Optional`isVisible

isVisible?: boolean

Whether the component is visible (for lazy loading)

`Optional`labels

labels?: Partial<FileManagerLabels>

Custom labels for internationalization

`Optional`onAddComment

onAddComment?: (fileId: string, content: string) => Promise<void>

Add a new comment to a file

`Optional`onCreateFolder

onCreateFolder?: (name: string, parentPath: string) => Promise<void>

Create a new folder

`Optional`onDelete

onDelete?: (files: FileEntry[]) => Promise<void>

Delete files

`Optional`onDeleteComment

onDeleteComment?: (fileId: string, commentId: string) => Promise<void>

Delete a comment from a file

`Optional`onDeleteFolder

onDeleteFolder?: (folder: FolderEntry) => Promise<void>

Delete a folder

`Optional`onDownload

onDownload?: (files: FileEntry[]) => Promise<void>

Download a file or files

`Optional`onEditComment

onEditComment?: (
    fileId: string,
    commentId: string,
    content: string,
) => Promise<void>

Edit a comment on a file

`Optional`onFetchFileTypes

onFetchFileTypes?: () => Promise<string[]>

Get list of available file types for filtering

`Optional`onFileCountChange

onFileCountChange?: (count: number) => void

Callback fired when the file count changes (useful for conditional UI)

`Optional`onFileEdit

onFileEdit?: (file: FileEntry) => void

Callback when a file should be opened in an editor (for types without inline viewers). If provided, prevents the fallback "no preview" viewer from opening.

`Optional`onFileOpen

onFileOpen?: (file: FileEntry) => void

Handle double-click to open file. This is always called when a file is opened.

`Optional`onGetAttendees

onGetAttendees?: () => Promise<{ userId: string; userName?: string }[]>

Get attendees for sharing dialog

`Optional`onGetComments

onGetComments?: (fileId: string) => Promise<FileComment[]>

Get comments for a specific file. When provided, enables the comments panel. Called when a file is selected and the comments panel is opened.

`Optional`onGetFileUrl

onGetFileUrl?: (file: FileEntry) => Promise<string>

Get presigned URL for file viewing

`Optional`onGetMarkers

onGetMarkers?: (
    fileId: string,
) => {
    authorId?: string;
    authorName?: string;
    color?: string;
    content: string;
    createdAt?: string;
    editedAt?: string;
    id: string;
    time: number;
}[]

Get saved timeline markers for a specific file

`Optional`onGetRegions

onGetRegions?: (
    fileId: string,
) => {
    channelIdx?: number;
    content: string;
    end: number;
    id: string;
    start: number;
}[]

Get saved regions for a specific file

`Optional`onMarkerAdd

onMarkerAdd?: (
    fileId: string,
    marker: {
        authorId?: string;
        authorName?: string;
        color?: string;
        content: string;
        createdAt?: string;
        editedAt?: string;
        id: string;
        time: number;
    },
) => void

Called when a new timeline marker is added

`Optional`onMarkerChange

onMarkerChange?: (
    fileId: string,
    marker: {
        authorId?: string;
        authorName?: string;
        color?: string;
        content: string;
        createdAt?: string;
        editedAt?: string;
        id: string;
        time: number;
    },
) => void

Called when a timeline marker is updated

`Optional`onMarkerDelete

onMarkerDelete?: (fileId: string, markerId: string) => void

Called when a timeline marker is deleted

`Optional`onMove

onMove?: (files: FileEntry[], newLocation: string) => Promise<void>

Move file(s) to a new location

`Optional`onNavigate

onNavigate?: (path: string) => void

Navigate to a folder path. When inside FileCacheProvider, this is auto-wired unless overridden.

`Optional`onRefresh

onRefresh?: () => void

Refresh the file list. When inside FileCacheProvider, this is auto-wired unless overridden.

`Optional`onRegionChange

onRegionChange?: (
    fileId: string,
    region: {
        channelIdx?: number;
        content: string;
        end: number;
        id: string;
        start: number;
    },
) => void

Called when a named region is created or updated

`Optional`onRegionDelete

onRegionDelete?: (fileId: string, regionId: string) => void

Called when a named region is deleted

`Optional`onRename

onRename?: (file: FileEntry, newName: string) => Promise<void>

Rename a file

`Optional`onSelect

onSelect?: (selection: { fileId: string; filename: string }) => void

Callback when a file is selected

`Optional`onShare

onShare?: (files: FileEntry[], userIds: string[]) => Promise<void>

Share files with users

`Optional`onSwitchToTab

onSwitchToTab?: (tabName: string, file: FileEntry) => void

Callback when switching to a specific tab (for smart opening)

`Optional`onUpload

onUpload?: (file: File, location: string) => Promise<void>

Upload a file. Returns void or throws on error.

`Optional`onViewModeChange

onViewModeChange?: (mode: FileManagerViewMode) => void

Callback when view mode changes

`Optional`refresh

refresh?: number

Trigger refresh from parent (increment to trigger refresh)

`Optional`renderProps

renderProps?: FileManagerRenderProps

Render props for advanced customization

`Optional`renderShareUserList

renderShareUserList?: (
    props: {
        availableUsers: { userId: string; userName?: string }[];
        isDisabled: boolean;
        onToggleUser: (userId: string) => void;
        selectedUserIds: Set<string>;
    },
) => ReactNode

Custom render function for the sharing dialog's user selection area. When provided, replaces the default checkbox user list in the share dialog.

`Optional`resourceTabMapping

resourceTabMapping?: {
    add?: Record<string, string>;
    remove?: string[];
    replace?: Record<string, string>;
}

Customize the mapping of resource types to sidebar tab names for smart opening. When a file is double-clicked and has no inline viewer, this mapping determines which tab to switch to via onSwitchToTab.

Example

// Add a custom resource type that opens in a "documents" tab
<FileManager resourceTabMapping={{ add: { 'custom-doc': 'documents' } }} />

// Remove a mapping so it falls through to the file viewer
<FileManager resourceTabMapping={{ remove: ['whiteboard'] }} />

// Replace the entire mapping
<FileManager resourceTabMapping={{ replace: { notes: 'notes', whiteboard: 'board' } }} />

`Optional`resourceViewerTypes

resourceViewerTypes?: { add?: string[]; remove?: string[]; replace?: string[] }

Override which resource types open in the inline FileViewer. By default, types like image, video, pdf, room-summary, etc. open in the viewer. Types not in this set (e.g., whiteboard, notes) route to tab switching instead.

Example

// Add a custom type to the viewer set
<FileManager resourceViewerTypes={{ add: ['my-custom-type'] }} />

// Remove a type so it routes to tab switching
<FileManager resourceViewerTypes={{ remove: ['room-summary'] }} />

// Replace the entire set
<FileManager resourceViewerTypes={{ replace: ['image', 'video', 'pdf'] }} />

`Optional`roomName

roomName?: string

Room name (derived from context when inside FileCacheProvider)

`Optional`showBothOwnedAndShared

showBothOwnedAndShared?: boolean

Whether to show both owned and shared files

`Optional`showBreadcrumbs

showBreadcrumbs?: boolean

Whether to show breadcrumb navigation

Default Value

true

`Optional`showOnlySharedFiles

showOnlySharedFiles?: boolean

Whether to show only files shared with user

`Optional`showToolbar

showToolbar?: boolean

Whether to show the toolbar

Default Value

true

`Optional`sortStorageKey

sortStorageKey?: string

localStorage key for persisting sort state. When provided, sort column and direction are saved and restored across sessions.

`Optional`styles

styles?: Partial<FileManagerStyles>

Custom style values

`Optional`sx

sx?: SxProps<Theme>

MUI sx styling prop

`Optional`userId

userId?: string

Current user's ID. When inside FileCacheProvider, this is derived from context unless overridden.

`Optional`viewMode

viewMode?: FileManagerViewMode

Controlled view mode (table or card). When provided, the component is controlled.

Interface FileManagerProps

Remarks

Example

Example

Example

Index

Properties

Properties

OptionalavailableTabs

Optionalcolors

Optionalcolumns

OptionalcurrentPath

OptionalcurrentUserId

OptionalcustomAction

OptionalcustomContextActions

OptionalcustomFilters

OptionalcustomViewers

OptionaldefaultFilterChip

OptionaldefaultViewMode

Default Value

OptionalenableDragDrop

Default Value

OptionalenableMarkers

Default Value

OptionalenableMultiSelect

Default Value

OptionalenableRegions

Default Value

OptionalenableSmartOpening

Default Value

OptionalfieldFormatters

Example

OptionalfileNameFormatter

Optionalfiles

OptionalfilterChipPriority

OptionalfilterChips

Example

OptionalfilterFileTypes

Optionalfolders

OptionalgetCommentCount

Optionalicons

OptionalisDownloading

OptionalisLoading

OptionalisRefreshing

OptionalisRoomOwner

OptionalisUploading

OptionalisVisible

Optionallabels

OptionalonAddComment

OptionalonCreateFolder

OptionalonDelete

OptionalonDeleteComment

OptionalonDeleteFolder

OptionalonDownload

OptionalonEditComment

OptionalonFetchFileTypes

OptionalonFileCountChange

OptionalonFileEdit

OptionalonFileOpen

OptionalonGetAttendees

OptionalonGetComments

OptionalonGetFileUrl

OptionalonGetMarkers

OptionalonGetRegions

OptionalonMarkerAdd

OptionalonMarkerChange

OptionalonMarkerDelete

OptionalonMove

OptionalonNavigate

OptionalonRefresh

OptionalonRegionChange

OptionalonRegionDelete

OptionalonRename

OptionalonSelect

OptionalonShare

OptionalonSwitchToTab

OptionalonUpload

OptionalonViewModeChange

Optionalrefresh

OptionalrenderProps

`Optional`availableTabs

`Optional`colors

`Optional`columns

`Optional`currentPath

`Optional`currentUserId

`Optional`customAction

`Optional`customContextActions

`Optional`customFilters

`Optional`customViewers

`Optional`defaultFilterChip

`Optional`defaultViewMode

`Optional`enableDragDrop

`Optional`enableMarkers

`Optional`enableMultiSelect

`Optional`enableRegions

`Optional`enableSmartOpening

`Optional`fieldFormatters

`Optional`fileNameFormatter

`Optional`files

`Optional`filterChipPriority

`Optional`filterChips

`Optional`filterFileTypes

`Optional`folders

`Optional`getCommentCount

`Optional`icons

`Optional`isDownloading

`Optional`isLoading

`Optional`isRefreshing

`Optional`isRoomOwner

`Optional`isUploading

`Optional`isVisible

`Optional`labels

`Optional`onAddComment

`Optional`onCreateFolder

`Optional`onDelete

`Optional`onDeleteComment

`Optional`onDeleteFolder

`Optional`onDownload

`Optional`onEditComment

`Optional`onFetchFileTypes

`Optional`onFileCountChange

`Optional`onFileEdit

`Optional`onFileOpen

`Optional`onGetAttendees

`Optional`onGetComments

`Optional`onGetFileUrl

`Optional`onGetMarkers

`Optional`onGetRegions

`Optional`onMarkerAdd

`Optional`onMarkerChange

`Optional`onMarkerDelete

`Optional`onMove

`Optional`onNavigate

`Optional`onRefresh

`Optional`onRegionChange

`Optional`onRegionDelete

`Optional`onRename

`Optional`onSelect

`Optional`onShare

`Optional`onSwitchToTab

`Optional`onUpload

`Optional`onViewModeChange

`Optional`refresh

`Optional`renderProps

`Optional`renderShareUserList

`Optional`resourceTabMapping

`Optional`resourceViewerTypes

`Optional`roomName

`Optional`showBothOwnedAndShared

`Optional`showBreadcrumbs

`Optional`showOnlySharedFiles

`Optional`showToolbar

`Optional`sortStorageKey

`Optional`styles

`Optional`sx

`Optional`userId

`Optional`viewMode