File Preview

A lazy preview of a single stored file — image, PDF or text — with metadata, resolving bytes only when it mounts.

Previews one stored file by key (or a resolved StoredFile). Images and PDFs prefer a direct url(), falling back to the gateway download proxy when the adapter can’t sign; text is fetched and shown inline. Bytes load only when the component mounts.

photos/sunset.jpg

—

"use client";

import { UploadIcon } from "lucide-react";
import type { ChangeEvent } from "react";
import { useRef, useState } from "react";

import { Button } from "@/components/ui/button";
import { demoFiles } from "@/lib/demo-files";
import { FilePreview } from "@/registry/files-sdk/file-preview/file-preview";

const Example = () => {
  const files = demoFiles;
  const inputRef = useRef<HTMLInputElement>(null);
  // Start on a seeded image so the preview is populated; uploading swaps it out.
  const [key, setKey] = useState<string>("photos/sunset.jpg");

  const handleChange = async (event: ChangeEvent<HTMLInputElement>) => {
    // Capture the element now — React nulls `currentTarget` after the handler's
    // synchronous phase, so it's gone by the time the upload below resolves.
    const input = event.currentTarget;
    const file = input.files?.[0];
    if (!file) {
      return;
    }
    const result = await files.upload(`demo/${file.name}`, file, {
      contentType: file.type,
    });
    setKey(result.key);
    input.value = "";
  };

  return (
    <div className="flex flex-col gap-4">
      <div>
        <Button
          onClick={() => inputRef.current?.click()}
          type="button"
          variant="outline"
        >
          <UploadIcon />
          Choose a file
        </Button>
        <input
          accept="image/*,text/*,application/pdf"
          aria-label="Choose a file to preview"
          className="hidden"
          onChange={(event) => void handleChange(event)}
          ref={inputRef}
          type="file"
        />
      </div>
      <FilePreview file={key} files={files} />
    </div>
  );
};

export default Example;

Installation

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

Usage

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

import { FilePreview } from "@/components/files-sdk/file-preview";

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

  return <FilePreview file={fileKey} files={files} />;
}

The footer shows the key, size, type and etag. Pass either a key string (the component head()s it for metadata) or an already-resolved StoredFile to skip that round-trip.

Props

PropType

filesUseFilesResult

A `useFiles()` instance — resolves metadata and bytes through it.

TypeUseFilesResult

filestring | StoredFile

A key string, or an already-resolved `StoredFile`.

Typestring | StoredFile

endpoint?string

Endpoint for the gateway download-proxy fallback. Default `"/api/files"`.

Typestring

className?string

Typestring