React API

import { DocumentExplorer } from '@document-explorer/react';
import '@document-explorer/react/styles.css';

<DocumentExplorer />

Data

Prop	Type	Default
data	readonly T[]	—
mapper	DocumentMapper<T>	identity
locale	string	browser default

Chrome

Prop	Type	Default
title	ReactNode	—
rootLabel	string	'Home'
className	string	—
style	CSSProperties	—

Views

Prop	Type	Default
view	'list' | 'grid' | 'tree'	uncontrolled
defaultView	same	'list'
views	ExplorerView[]	['list', 'grid']

Behaviour

Prop	Type	Default
search	boolean | { scope?, searchableFields?, matchMode?, placeholder? }	false
sort	{ key?, direction?, foldersFirst? }	{ key: 'name', direction: 'asc', foldersFirst: true }
columns	(ColumnDef | string)[]	Name, Type, Size, Modified
columnAlign	'left' | 'center' | 'right'	'left'
resizableColumns	boolean	false
columnWidths	Record<string, number>	{}
selection	boolean | { mode?, files?, folders?, max? }	false
actions	{ view?, download? } | ActionDef[]	none
interaction	{ folderClick?, fileClick?, doubleClick? }	open / select / open
renderers	Renderers	—
loading	boolean	false
error	unknown	—

Events

onFolderOpen · onDocumentOpen · onSelectionChange · onSearch · onSort · onViewChange · onView · onDownload · onAction(actionId, item) · onColumnResize(key, width, widths)

Types

interface ColumnDef {
  key: string;
  label: string;
  sortable?: boolean;
  /** `'left'` (default), `'center'` or `'right'`. Overrides `columnAlign`. */
  align?: 'left' | 'center' | 'right';
  /** Tabular numerals. Affects digit width, not position. */
  numeric?: boolean;
  width?: string;
  optional?: boolean;
  /** Set false to pin this column when `resizableColumns` is on. */
  resizable?: boolean;
  minWidth?: number;
  maxWidth?: number;
  render?: (item: DocumentItem) => ReactNode;
}

interface ActionDef {
  id: string;
  label: string;
  icon?: ReactNode;
  visible?: (item: DocumentItem) => boolean;
  danger?: boolean;
}

interface Renderers {
  file?: (item: DocumentItem) => ReactNode;
  folder?: (item: DocumentItem) => ReactNode;
  row?: (item: DocumentItem) => ReactNode;
  icon?: (item: DocumentItem) => ReactNode;
  empty?: () => ReactNode;
  loading?: () => ReactNode;
  error?: (error: unknown) => ReactNode;
  toolbar?: () => ReactNode;
}

avatarColumn(options)

A ready-made column that renders a person. Returns a ColumnDef.

avatarColumn({ key: 'metadata.owner', display: 'avatar', image: 'metadata.pic' })

Accepts every ColumnDef field plus name, image, display, tooltip, color and fallback. See avatars.

AvatarCell is exported too, for use inside your own render.

badgeColumn(options)

A ready-made status column. Returns a ColumnDef.

badgeColumn({ key: 'metadata.status', variant: 'pill', tones: { draft: 'info' } })

Accepts every ColumnDef field plus value, tones, format, variant and fallbackTone. See badges.

BadgeCell is exported too, for use inside your own render.

useDocumentExplorer()

The headless hook behind the component.

const { store, snapshot } = useDocumentExplorer({ data, mapper, selection: true });

Returns the core store and its current snapshot, wired through useSyncExternalStore.

Exported sub-components

Breadcrumbs · SearchInput · ViewSwitcher · ListView · GridView · TreeView · SelectionBar · EmptyState · LoadingState · ErrorState

Plus ICONS, UiIcons, iconFor, DEFAULT_COLUMNS, resolveColumns and resolveActions.

The engine is re-exported too — createExplorerStore, normalize, registerFileType, resolveFileType, formatBytes, formatDate — so a consumer needs only one dependency.