FilePeek

A Google Drive-style file previewer component for React. Supports images, videos, audio, PDFs, documents, and more — with zoom, pan, rotate, and gallery navigation.

✨ Features

• 🖼️ Image preview with zoom (Ctrl+scroll), pan (drag), rotate (R key)
• 🎬 Video preview with native HTML5 controls
• 🎵 Audio preview with styled player
• 📄 PDF preview via embedded iframe
• 📁 Generic fallback with file info and download button
• ⬅️➡️ Gallery navigation for multi-file preview
• ⌨️ Keyboard shortcuts (Esc, arrows, Ctrl+/-, R)
• 🎨 Google Drive-style dark overlay with blur & zoom controls
• 📦 Zero config — CSS is bundled, just import and use

📦 Installation

npm install filepeek lucide-react

lucide-react is a required peer dependency for icons.

🚀 Quick Start

import { useState } from "react";
import { FilePreviewer, type PreviewFile } from "filepeek";
// CSS is auto-imported from the package

function App() {
  const [open, setOpen] = useState(false);
  const [files, setFiles] = useState<PreviewFile[]>([]);

  const handleImageClick = () => {
    setFiles([
      { url: "https://example.com/photo1.jpg", name: "Photo 1.jpg", size: 2_400_000 },
      { url: "https://example.com/photo2.jpg", name: "Photo 2.jpg", size: 1_800_000 },
    ]);
    setOpen(true);
  };

  return (
    <>
      <button onClick={handleImageClick}>View Photos</button>

      <FilePreviewer
        open={open}
        onClose={() => setOpen(false)}
        files={files}
        initialIndex={0}
      />
    </>
  );
}

📖 API Reference

<FilePreviewer />

| Prop | Type | Default | Description | |------|------|---------|-------------| | open | boolean | — | Whether the previewer is visible | | onClose | () => void | — | Called when the user closes the previewer | | files | PreviewFile[] | — | Array of files to preview | | initialIndex | number | 0 | Index of the initially active file | | onDownload | (file: PreviewFile) => void | auto | Custom download handler | | onPrint | (file: PreviewFile) => void | auto | Custom print handler | | className | string | — | Extra class for the overlay |

PreviewFile

interface PreviewFile {
  url: string;          // File URL
  name?: string;        // Display name
  mimeType?: string;    // MIME type (auto-detected if omitted)
  size?: number;        // File size in bytes
  caption?: string;     // Caption shown below the preview
  thumbnail?: string;   // Optional thumbnail URL
}

useFilePreviewer hook

Advanced usage — access the internal state directly:

import { useFilePreviewer } from "filepeek";

const {
  zoom, zoomIn, zoomOut, resetZoom,
  activeIndex, next, prev,
  rotation, rotateClockwise,
  pan, setPan,
  loading, error,
} = useFilePreviewer(files, initialIndex);

Utility functions

import { detectFileType, formatFileSize, getDisplayName } from "filepeek";

detectFileType({ url: "photo.jpg" }); // "image"
formatFileSize(2_450_000);            // "2.3 MB"
getDisplayName({ url: "/path/to/file.pdf" }); // "file.pdf"

⌨️ Keyboard Shortcuts

| Key | Action | |-----|--------| | Esc | Close previewer | | ← → | Navigate files | | Ctrl + + | Zoom in | | Ctrl + − | Zoom out | | Ctrl + 0 | Reset zoom | | R | Rotate 90° clockwise | | Ctrl + Scroll | Zoom with mouse wheel | | Drag | Pan when zoomed in |

🎨 Supported File Types

| Type | Extensions | Preview | |------|-----------|---------| | Image | jpg, png, gif, webp, svg, avif... | Full preview + zoom/pan/rotate | | Video | mp4, webm, ogg, mov... | HTML5 video player | | Audio | mp3, wav, ogg, flac, aac... | Styled audio player | | PDF | pdf | Embedded iframe viewer | | Document | doc, docx, odt, rtf | File info + download | | Spreadsheet | xls, xlsx, ods, csv | File info + download | | Presentation | ppt, pptx, odp | File info + download | | Code | js, ts, py, java, go... | File info + download | | Other | * | Generic fallback |

📄 License

MIT © Abiral Khadka