File Browser

A folder-aware browser that descends into common prefixes with a breadcrumb trail — driven by useFiles.

Lists a folder with list({ delimiter }), so common prefixes surface as folders you can click into. A breadcrumb trail tracks where you are, and cursor-based “load more” pages through large folders. On adapters that can’t delimit, everything simply appears as files at the root.

"use client";

import { useState } from "react";

import { demoFiles } from "@/lib/demo-files";
import { FileBrowser } from "@/registry/files-sdk/file-browser/file-browser";

const Example = () => {
  const files = demoFiles;
  const [selected, setSelected] = useState<string>();

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <FileBrowser
        files={files}
        initialPrefix="documents/"
        onSelect={(file) => setSelected(file.key)}
      />
      {selected && (
        <p className="text-muted-foreground text-xs">Selected: {selected}</p>
      )}
    </div>
  );
};

export default Example;

Installation

npx shadcn@latest add https://files-sdk.dev/r/file-browser.json

Usage

import { useFiles } from "files-sdk/react";

import { FileBrowser } from "@/components/files-sdk/file-browser";

export function Browser() {
  const files = useFiles({ endpoint: "/api/files" });

  return (
    <FileBrowser
      files={files}
      initialPrefix="photos/"
      onSelect={(file) => console.log(file.key)}
    />
  );
}

Folders come straight from list()’s prefixes, which the gateway returns whenever the adapter supports a delimiter. The component owns its own navigation state; pass onSelect to react to file clicks (open a preview, generate a share link, etc.).

Props