Component reference
FileManager
Browse and manage a project's assets.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Selection
Ctrl/Cmd click adds entries; Shift click selects a range.
Nothing selected yet.
Last opened
Double click a folder to navigate, or a file to hand it to the host application.
No entry opened yet.
Width adapts to the available space
"use client";
import { useState } from "react";
import {
type PimoluFileEntry,
type PimoluFileManagerView,
FileManager,
Card,
CardHeader,
CardTitle,
CardDescription,
CardContent,
Badge
} from "@pimolu/react";
const initialEntries: PimoluFileEntry[] = [
{
id: "brand",
name: "Brand",
type: "folder",
modified: new Date(2026, 9, 14),
children: [
{
id: "logo-suite",
name: "logo-suite.svg",
type: "file",
size: 84000,
mime: "image/svg+xml",
modified: new Date(2026, 9, 12),
},
{
id: "guidelines",
name: "brand-guidelines.pdf",
type: "file",
size: 4800000,
mime: "application/pdf",
modified: new Date(2026, 9, 14),
},
{
id: "tokens",
name: "color-tokens.json",
type: "file",
size: 18400,
mime: "application/json",
modified: new Date(2026, 9, 9),
},
],
},
{
id: "deliverables",
name: "Deliverables",
type: "folder",
modified: new Date(2026, 8, 30),
children: [
{
id: "q4-report",
name: "Q4-research.pdf",
type: "file",
size: 6200000,
mime: "application/pdf",
modified: new Date(2026, 9, 3),
},
{
id: "budget",
name: "budget.xlsx",
type: "file",
size: 312000,
mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
modified: new Date(2026, 9, 8),
},
{
id: "demo",
name: "product-demo.mp4",
type: "file",
size: 48000000,
mime: "video/mp4",
modified: new Date(2026, 9, 16),
},
],
},
{
id: "engineering",
name: "Engineering",
type: "folder",
modified: new Date(2026, 9, 18),
children: [
{
id: "architecture",
name: "architecture.md",
type: "file",
size: 12600,
mime: "text/markdown",
modified: new Date(2026, 9, 18),
},
{
id: "sdk",
name: "sdk-release.zip",
type: "file",
size: 2100000,
mime: "application/zip",
modified: new Date(2026, 9, 17),
},
],
},
{
id: "readme",
name: "README.md",
type: "file",
size: 2400,
mime: "text/markdown",
modified: new Date(2026, 9, 19),
},
{
id: "roadmap",
name: "roadmap-2027.pdf",
type: "file",
size: 980000,
mime: "application/pdf",
modified: new Date(2026, 9, 20),
},
];
const dateFormat = new Intl.DateTimeFormat("en-US", {
month: "short",
day: "numeric",
year: "numeric",
});
function removeEntries(entries: PimoluFileEntry[], ids: Set<string>): PimoluFileEntry[] {
return entries
.filter((entry) => !ids.has(entry.id))
.map((entry) => entry.children
? {
...entry,
children: removeEntries([...entry.children], ids),
}
: entry);
}
function ProjectAssetsExample() {
const [entries, setEntries] = useState<PimoluFileEntry[]>(initialEntries);
const [view, setView] = useState<PimoluFileManagerView>("list");
const [selected, setSelected] = useState<PimoluFileEntry[]>([]);
const [opened, setOpened] = useState<PimoluFileEntry | null>(null);
return (
<div className="grid gap-5 min-w-0">
<FileManager
aria-label="Project assets"
entries={entries}
view={view}
onViewChange={setView}
onSelect={setSelected}
onOpen={setOpened}
onDelete={(deleted) => {
const ids = new Set(deleted.map((entry) => entry.id));
setEntries((current) => removeEntries(current, ids));
setSelected((current) => current.filter((entry) => !ids.has(entry.id)));
}}
/>
<div
className="grid grid-cols-[repeat(auto-fit,minmax(min(100%,280px),1fr))] gap-6 min-w-0"
>
<Card>
<CardHeader>
<CardTitle>Selection</CardTitle>
<CardDescription>
Ctrl/Cmd click adds entries; Shift click selects a range.
</CardDescription>
</CardHeader>
<CardContent className="grid gap-5 min-w-0">
<div className="flex flex-wrap items-center gap-3 min-w-0">
<Badge variant="neutral">
{view} view
</Badge>
<Badge variant="primary">
{selected.length} selected
</Badge>
</div>
{
selected.length > 0
? (<ul className="grid gap-5 min-w-0">
{
selected.map((entry) => (<li key={entry.id}>
{entry.name}
</li>))
}
</ul>)
: (<p className="text-sm text-muted">Nothing selected yet.</p>)
}
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle>Last opened</CardTitle>
<CardDescription>
Double click a folder to navigate, or a file to hand it to the
host application.
</CardDescription>
</CardHeader>
<CardContent className="grid gap-5 min-w-0">
{
opened
? (<>
<p>{opened.name}</p>
<div className="flex flex-wrap items-center gap-3 min-w-0">
<Badge variant="neutral">
{opened.type}
</Badge>
<Badge variant="neutral">
{
opened.modified
? dateFormat.format(opened.modified)
: "No date"
}
</Badge>
</div>
</>)
: (<p className="text-sm text-muted">No entry opened yet.</p>)
}
</CardContent>
</Card>
</div>
</div>
);
}
export function DemoExample() {
return (<ProjectAssetsExample />);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Single-file selection
Browse local mock files with real folder navigation and selection feedback.
Open a nested folder
Browse local mock files with real folder navigation and selection feedback.
Asset picker
Grid tiles with single selection, shown without folders.
Usage
File actions report application intent; connect them to real permissions and storage before shipping.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluFileManagerSort
Type source| Name | Type | Default | Description |
|---|---|---|---|
byRequired | PimoluFileManagerSortBy | — | Public Pimolu prop; see the source declaration for details. |
directionRequired | PimoluFileManagerSortDirection | — | Public Pimolu prop; see the source declaration for details. |
byRequiredPimoluFileManagerSortByNo default extracted.
Public Pimolu prop; see the source declaration for details.
directionRequiredPimoluFileManagerSortDirectionNo default extracted.
Public Pimolu prop; see the source declaration for details.
PimoluFileEntry
Type source| Name | Type | Default | Description |
|---|---|---|---|
idRequired | string | — | Stable identifier. |
nameRequired | string | — | Visible name. |
typeRequired | PimoluFileEntryType | — | Whether the entry can be opened as a folder. |
size | number | undefined | — | Size in bytes, for files. |
modified | Date | undefined | — | Last modification date. |
mime | string | undefined | — | MIME type, used to choose the icon. |
children | readonly PimoluFileEntry[] | undefined | — | Nested children. Their parent is inferred from this entry. |
parentId | string | null | undefined | — | Parent folder id for flat data. `null` means the root. |
idRequiredstringNo default extracted.
Stable identifier.
nameRequiredstringNo default extracted.
Visible name.
typeRequiredPimoluFileEntryTypeNo default extracted.
Whether the entry can be opened as a folder.
sizenumber | undefinedNo default extracted.
Size in bytes, for files.
modifiedDate | undefinedNo default extracted.
Last modification date.
mimestring | undefinedNo default extracted.
MIME type, used to choose the icon.
childrenreadonly PimoluFileEntry[] | undefinedNo default extracted.
Nested children. Their parent is inferred from this entry.
parentIdstring | null | undefinedNo default extracted.
Parent folder id for flat data. `null` means the root.
PimoluFileManagerProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
entriesRequired | readonly PimoluFileEntry[] | — | Full data set. Only the direct children of the current folder are shown. |
view | PimoluFileManagerView | undefined | — | Controlled view. |
defaultView | PimoluFileManagerView | undefined | "list" | Initial view when uncontrolled. Defaults to "list". |
onViewChange | ((view: PimoluFileManagerView) => void) | undefined | — | Called when the List/Grid toggle changes. |
selected | readonly string[] | undefined | — | Controlled selected ids. |
defaultSelected | readonly string[] | undefined | [] | Initial selected ids when uncontrolled. |
onSelectionChange | ((ids: string[], entries: PimoluFileEntry[]) => void) | undefined | — | Called with the selected ids and their entries whenever selection changes. |
onSelect | ((entries: PimoluFileEntry[]) => void) | undefined | — | Called with the selected entries whenever selection changes. |
path | readonly string[] | undefined | — | Controlled folder path, from the root to the current folder. |
defaultPath | readonly string[] | undefined | the root | Initial folder path when uncontrolled. Defaults to the root. |
onPathChange | ((path: string[]) => void) | undefined | — | Called when the current folder changes. |
selectionMode | "single" | "multiple" | undefined | "multiple" | "single" replaces the selection; "multiple" supports Ctrl/Cmd and Shift. |
search | string | undefined | — | Controlled search term. |
defaultSearch | string | undefined | "" | Initial search term when uncontrolled. |
onSearchChange | ((value: string) => void) | undefined | — | Called whenever the search term changes. |
sort | PimoluFileManagerSort | undefined | — | Controlled sort. |
defaultSort | PimoluFileManagerSort | undefined | name ascending | Initial sort when uncontrolled. Defaults to name ascending. |
onSortChange | ((sort: PimoluFileManagerSort) => void) | undefined | — | Called whenever the sort column or direction changes. |
onOpen | ((entry: PimoluFileEntry) => void) | undefined | — | Called when a folder is opened or when a file is double-clicked (or activated with Enter). |
onDelete | ((entries: PimoluFileEntry[]) => void) | undefined | — | Called with the selected entries when Delete is pressed or the toolbar action is used. |
locale | string | undefined | "en-US" | BCP 47 locale used for dates and name sorting. Defaults to "en-US". |
rootLabel | string | undefined | "Files" | Label of the root breadcrumb. Defaults to "Files". |
foldersFirst | boolean | undefined | true | Keep folders before files regardless of the sort column. Defaults to true. |
className | string | undefined | — | Class applied to the outer file manager. |
aria-label | string | undefined | "File manager" | Accessible name of the file manager. Defaults to "File manager". |
entriesRequiredreadonly PimoluFileEntry[]No default extracted.
Full data set. Only the direct children of the current folder are shown.
viewPimoluFileManagerView | undefinedNo default extracted.
Controlled view.
defaultViewPimoluFileManagerView | undefinedDefault: "list"
Initial view when uncontrolled. Defaults to "list".
onViewChange((view: PimoluFileManagerView) => void) | undefinedNo default extracted.
Called when the List/Grid toggle changes.
selectedreadonly string[] | undefinedNo default extracted.
Controlled selected ids.
defaultSelectedreadonly string[] | undefinedDefault: []
Initial selected ids when uncontrolled.
onSelectionChange((ids: string[], entries: PimoluFileEntry[]) => void) | undefinedNo default extracted.
Called with the selected ids and their entries whenever selection changes.
onSelect((entries: PimoluFileEntry[]) => void) | undefinedNo default extracted.
Called with the selected entries whenever selection changes.
pathreadonly string[] | undefinedNo default extracted.
Controlled folder path, from the root to the current folder.
defaultPathreadonly string[] | undefinedDefault: the root
Initial folder path when uncontrolled. Defaults to the root.
onPathChange((path: string[]) => void) | undefinedNo default extracted.
Called when the current folder changes.
selectionMode"single" | "multiple" | undefinedDefault: "multiple"
"single" replaces the selection; "multiple" supports Ctrl/Cmd and Shift.
searchstring | undefinedNo default extracted.
Controlled search term.
defaultSearchstring | undefinedDefault: ""
Initial search term when uncontrolled.
onSearchChange((value: string) => void) | undefinedNo default extracted.
Called whenever the search term changes.
sortPimoluFileManagerSort | undefinedNo default extracted.
Controlled sort.
defaultSortPimoluFileManagerSort | undefinedDefault: name ascending
Initial sort when uncontrolled. Defaults to name ascending.
onSortChange((sort: PimoluFileManagerSort) => void) | undefinedNo default extracted.
Called whenever the sort column or direction changes.
onOpen((entry: PimoluFileEntry) => void) | undefinedNo default extracted.
Called when a folder is opened or when a file is double-clicked (or activated with Enter).
onDelete((entries: PimoluFileEntry[]) => void) | undefinedNo default extracted.
Called with the selected entries when Delete is pressed or the toolbar action is used.
localestring | undefinedDefault: "en-US"
BCP 47 locale used for dates and name sorting. Defaults to "en-US".
rootLabelstring | undefinedDefault: "Files"
Label of the root breadcrumb. Defaults to "Files".
foldersFirstboolean | undefinedDefault: true
Keep folders before files regardless of the sort column. Defaults to true.
classNamestring | undefinedNo default extracted.
Class applied to the outer file manager.
aria-labelstring | undefinedDefault: "File manager"
Accessible name of the file manager. Defaults to "File manager".
Accessibility
- Test selection, contextual actions, rename/delete confirmation and focus after a file disappears.