API reference

@thefinder/react

The file manager UI. Its only dependencies are react and react-dom (≥ 18, peer); styles are plain CSS.

"use client";
import { TheFinder } from "@thefinder/react";
import "@thefinder/react/styles.css";

<div style={{ height: "100vh" }}>
  <TheFinder endpoint="/api/files" locale="en" />
</div>

Import styles.css once, anywhere in your app. The component fills the height of its parent (change it with the height prop).

<TheFinder />#

Connection#

Appearance#

Initial state#

Prefs:

Events#

The onChange event: { type, entries?, ids? }. entries are new or updated items, ids are the ids of removed items.

Picker mode#

When onSelect is given the component acts as a picker: a "Select" button appears in the bottom bar and double-clicking a file selects it. For a modal picker, useFilePicker is more convenient.

type Accept = string | string[] | ((entry: Entry) => boolean);
// "image/*"            a MIME group
// ".pdf,.docx"         extensions
// ["image/png", ".svg"]
// (e) => e.size < 2_000_000

matchesAccept(entry, accept) is exported so you can apply the same rule in your own code. Folders never match.

File picker#

useFilePicker(options)#

const picker = useFilePicker({ endpoint: "/api/files", accept: "image/*" });

<button disabled={picker.isOpen} onClick={async () => {
  const files = await picker.open();
  if (files) setCover(files[0].url);
}}>Choose image</button>

Returns { open(overrides?), isOpen }.

• open returns a Promise<PickedFile[] | null>; if the user cancels it resolves null. overrides changes options for that one opening: picker.open({ multiple: true }).
• isOpen is true while the picker is open.
• The hook always uses the latest options on every render; you don't need to wrap the options object in useMemo.

openFilePicker(options)#

The same picker outside React (vanilla JS, Vue, rich text editors). It appends a <dialog> to the end of <body> and removes it on close. React and React DOM must be bundled on the page.

import { openFilePicker } from "@thefinder/react";
import "@thefinder/react/styles.css";

const files = await openFilePicker({ endpoint: "/api/files", accept: ".pdf" });
if (files) input.value = files[0].url;

On the server (no document) it resolves null right away.

FilePickerOptions#

All <TheFinder /> props (except onSelect, onCancel, height, style), plus:

The picker closes with Escape, a click on the backdrop or the "Cancel" button. Escape first closes any open menu or dialog. In a popup window it closes with the "Cancel" button or the window's close button.

PickedFile#

Entry plus url: string. If the volume has a url, that address is used ("/uploads/a.png"); otherwise the API's file URL. pickedUrl(entry, client, absolute?) is exported to build the same URL in your own code.

Own window#

Like elFinder, theFinder can run in a separate browser window. Nothing has to be served for it: the window is an empty same-origin page that the opening page renders into with its own code and stylesheets, so every prop (custom editors, headers, callbacks) works as usual.

// The picker in a window: same promise, same result.
const files = await openFilePicker({ endpoint: "/api/files", accept: "image/*", popup: true });
const picker = useFilePicker({ endpoint: "/api/files", popup: { width: 960, height: 640 } });

// The whole file manager in a window.
const finder = openFinderWindow({ endpoint: "/api/files" }, { title: "Files" });
await finder?.closed; // finder.window, finder.close()

openFinderWindow(props, options?) takes <TheFinder /> props (except height) and { width = 1120, height = 720, title = "theFinder" }. It returns { window, close, closed }, or null when the browser blocks the popup.

• Call it from a click handler, or the browser blocks the popup. The picker then falls back to the dialog.
• The window is centered over the page and closes with it: it runs on the page's code.
• Stylesheets of the page (and ones added later) are copied in, as are the attributes of <html> (class="dark", lang).
• With the CKEditor connector: picker: { popup: true }.

Custom editors#

The editors prop adds an item to the "Open with" menu for matching files. The editor opens full-size inside the file manager.

import type { CustomEditor } from "@thefinder/react";

const csvViewer: CustomEditor = {
  id: "csv",
  label: "Open as table",
  match: (entry) => entry.name.toLowerCase().endsWith(".csv"),
  render: ({ entry, store, onClose }) => <CsvTable url={store.fileUrl(entry)} title={entry.name} onClose={onClose} />,
};

<TheFinder endpoint="/api/files" editors={[csvViewer]} />

Useful store members inside an editor:

Saving example:

const { entry: saved } = await store.client.putContent(entry.id, text);
store.updateEntry(saved);
store.toast("Saved", "success");

Store and hooks#

The component uses a small store (FinderStore) built on useSyncExternalStore. The store is reachable only from components rendered inside <TheFinder /> (for example custom editors).

The store methods (open, select, upload, paste, remove…) were written for the UI itself. You can use them, but their signatures may change during 0.x.

i18n#

To add a new language, translate every key and pass it in; anything left out shows in English:

import { locales, type Messages } from "@thefinder/react";

const de: Partial<Messages> = { upload: "Hochladen", newFolder: "Neuer Ordner" /* ... */ };
<TheFinder endpoint="/api/files" locale="de" messages={de} />

See the locales.en object for the full list of keys.

Icons#

The UI's hand-drawn SVG icons can be used in your own components too:

Theming#

All styles live in @layer thefinder. Any rule you write outside the layer wins, no !important needed. The root element is .tf-root. It carries the data-theme (light, dark, auto), data-skin (classic, macos) and data-density attributes.

.tf-root {
  --tf-accent: #0f766e;
  --tf-radius: 4px;
  --tf-font: "Inter", system-ui, sans-serif;
}
.tf-root[data-theme="dark"] {
  --tf-bg: #101418;
}

Every class is prefixed with tf-. Classes other than the variables are internal structure and may change in minor releases.

Re-exports#

createClient, TheFinderClient, ApiError, encodeId and the Entry, VolumeInfo types come straight from @thefinder/core/client.

This page is generated from docs/api/react.md.