File Thumbnail

File Thumbnail gives document lists, upload queues, file browsers, and attachment trays one thumbnail component for every file source. Pass a browser File, a URL/blob/text source, an external image preview, or custom rendered content; the component handles the frame, loading shimmer, first-unit document rendering, fade-in, and fallback state.

Image

PDF

DOCX

PPTX

XLSX

CSV

Markdown

HTML

JSON

Code

Text

TIFF

"use client";

import * as React from "react";

import { cn } from "@/lib/utils";
import type { FileCategory } from "@/lib/viewer-source";
import { FileThumbnail } from "@/components/ui/file-thumbnail";

/**
 * The hero showcase: one bordered card with a large, labeled, *square* preview

View Code

Installation

pnpmnpmyarnbun
Copy
pnpm dlx shadcn@latest add @retab/file-thumbnail

Usage

Copyimport { FileThumbnail } from "@/components/ui/file-thumbnail";
 
export function PdfThumbnail({ file }: { file: File }) {
  return (
    <FileThumbnail file={file} thumbnailShape="square" thumbnailSize="md" />
  );
}
 
export function UrlThumbnail() {
  return (
    <FileThumbnail
      source={{
        kind: "url",
        url: "/contract.pdf",
        fileName: "contract.pdf",
        mimeType: "application/pdf",
      }}
      thumbnailShape="square"
      thumbnailSize="md"
    />
  );
}

States

FileThumbnail renders supported documents to their first unit: page 1 for PDF and DOCX, the first sheet for XLSX, the first slide for PPTX, the first TIFF frame, the HTML body for MSG emails, or the head of CSV, text, markdown, and HTML files. Images render directly. Unsupported files fall back to the compact extension surface.

LoadedpreviewImageUrl

Loadingstate="loading"

Fallbackno preview

xlsx

CustompreviewContent

640 × 480

"use client";

import * as React from "react";

import { FileThumbnail } from "@/components/ui/file-thumbnail";

// A self-contained "rendered page" image so the demo works offline.
const pagePreview =
  "data:image/svg+xml;utf8," +
  encodeURIComponent(

View Code

When you already have a generated preview, pass it directly:

Copy<FileThumbnail
  file={{ name: "invoice.pdf", type: "application/pdf" }}
  previewImageUrl="/previews/invoice-page-1.png"
/>
 
<FileThumbnail
  file={{ name: "custom.bin", type: "application/octet-stream" }}
  previewContent={<div className="grid size-full place-items-center">Ready</div>}
/>

Use state="loading" or state="error" when an external thumbnail pipeline is in charge of the preview lifecycle.

File Tooltip Example

Keep TooltipContent padding-free when the tooltip is only a larger file preview. The tooltip body can be just FileThumbnail, with the trigger owning the file name and accessible label.

loan-application.pdfPDF - 1 page

"use client";

import * as React from "react";

import { FileThumbnail } from "@/components/ui/file-thumbnail";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip";

View Code

Useful Behaviors

• Accepts browser File objects, URL sources, Blob sources, text sources, external preview image URLs, or custom React preview content.
• Renders only the first unit of supported documents, never the whole document.
• Shows a shimmer while document renderers load or an image preview decodes.
• Falls back to a muted extension surface for unsupported files and errors.
• Keeps the visual frame consistent across generated and externally supplied previews.

API Reference

FileThumbnail

file is enough for browser uploads. Use source for URL, Blob, or inline text sources. Use as only when the file name or MIME type is missing, wrong, or intentionally viewed as another supported category.

previewContent and previewImageUrl take priority over generated document rendering. That keeps the component useful when another system already produced the thumbnail.

FileThumbnail also forwards standard div props such as aria-label, data-*, event handlers, and style. Its internal data-slot="file-thumbnail" is kept stable for styling and tests.

ThumbnailFile

Source

"use client";

import type { ViewerSource } from "@/lib/viewer-source";
import { GeneratedFileThumbnail } from "@/components/file-thumbnail/generated-preview";

import {
  FileThumbnailFrame,
  FileThumbnailShimmer,
  hasRenderablePreviewContent,
  resolveFileThumbnailState,
} from "./file-thumbnail-frame";
import type {