👁️ @file-preview-viewer/viewer v1.2.4
← Live Demo npm i @file-preview-viewer/viewer GitHub

Interactive Documentation & API Reference

Learn how to integrate @file-preview-viewer/viewer into your application. Explore every configuration property, how to configure it in React, Angular, Vue 3, or Vanilla JS, and understand the exact visual and behavioral effect it produces.

⚙️ Preferred Framework:

📦 Installation & Framework Setup

Install the universal library into your project using npm, pnpm, or yarn. One single dependency supports all frameworks and 50+ file formats.

npm
npm i @file-preview-viewer/viewer
pnpm
pnpm add @file-preview-viewer/viewer
yarn
yarn add @file-preview-viewer/viewer
React Component (JSX / TSX)
import { FilePreview } from '@file-preview-viewer/viewer/react';
import '@file-preview-viewer/viewer/styles.css';

export function DocumentViewer({ fileUrl }) {
  return (
    <div style={{ width: '100%', height: '800px' }}>
      <FilePreview
        src={fileUrl} // URL string, File, Blob, or ArrayBuffer
        options={{
          theme: 'light',
          showToolbar: true,
          showFileName: true
        }}
        onLoaded={(meta) => console.log('Document loaded:', meta)}
      />
    </div>
  );
}

🎛️ PreviewViewerOptions Reference

Detailed guide for every configuration property passed into the viewer.

showToolbar boolean
Default: true
Controls whether the built-in toolbar (containing zoom, navigation, search, print, download, and fullscreen actions) is displayed or completely hidden.
💻 How to Set
<FilePreview
  src={file}
  options={{
    showToolbar: false // 👈 Hides toolbar completely
  }}
/>
👁️ What Effect It Has
  • When false: Completely removes the toolbar element from the DOM with zero vertical height, giving 100% of the viewport space to the document preview. Ideal for clean embed widgets or custom application toolbars.
  • When true: Renders the full toolbar equipped with zoom controls, search bar, download/print buttons, and page indicators.
  • Dynamic Switching: Can be toggled on-the-fly at runtime using viewer.setShowToolbar(boolean) or viewer.toggleToolbar() without reloading the file.
🎚️ Visual Difference: true renders the 40px action toolbar; false collapses it to 0px.
showFileName boolean
Default: true
Controls whether the document title header bar (displaying the file icon, file name, and format badge like "XLSX" or "PDF") is visible above the toolbar.
💻 How to Set
<FilePreview
  src={file}
  options={{
    showFileName: false // 👈 Hides top title bar
  }}
/>
👁️ What Effect It Has
  • When true: Displays a sleek header bar above the toolbar with 📄 FileName.ext and a colored badge such as DOCX, PDF, or XLSX.
  • When false: Completely hides the title header bar, useful when your page already provides its own heading or tab title.
📄 Title Bar: 📄 Repository.xlsx [XLSX]
fileName string
Default: derived from source
Custom display name override for the file. Useful when previewing raw Blobs, ArrayBuffers, or UUID/hashed URLs that lack human-readable filenames.
💻 How to Set
<FilePreview
  src={blobData}
  options={{
    fileName: 'Annual_Financial_Report_2026.xlsx'
  }}
/>
👁️ What Effect It Has
  • Overrides the name shown in the preview title bar.
  • Sets the default filename used when the user clicks the Download button.
  • Sets the window title when opened in a separate full window.
🏷️ Download Name: User saves with the clean custom filename instead of blob:http...
theme 'light' | 'dark' | 'auto'
Default: 'light'
Specifies the color theme of the viewer container, toolbar, thumbnail panels, and dialogs.
💻 How to Set
<FilePreview
  src={file}
  options={{
    theme: 'dark' // 'light' | 'dark' | 'auto'
  }}
/>
👁️ What Effect It Has
  • 'light': Crisp white background (#ffffff / #f8fafc), slate text, and light borders.
  • 'dark': Dark slate background (#0f172a / #1e293b), light text, dark toolbar and search inputs.
  • 'auto': Automatically responds to the user's OS system color preference via prefers-color-scheme media query.
🌓 Theme Mode: Toolbar and UI widgets seamlessly adapt without altering document page content.
toolbarPosition 'top' | 'bottom'
Default: 'top'
Controls the physical placement of the action toolbar relative to the document preview canvas.
💻 How to Set
<FilePreview
  src={file}
  options={{
    toolbarPosition: 'bottom' // 👈 Places toolbar at bottom
  }}
/>
👁️ What Effect It Has
  • 'top': Standard desktop reader layout — title bar and toolbar sit above the document.
  • 'bottom': Mobile/touch friendly bottom bar layout — controls are positioned at the bottom of the container within easy reach.
📍 Position: Swaps the flex order of .fp-toolbar-container and document viewport.
fitMode 'width' | 'page'
Default: 'width'
Determines how pages and documents are automatically scaled to fit within the viewport on initial render and during window resize.
💻 How to Set
<FilePreview
  src={file}
  options={{
    fitMode: 'page' // 'width' (default) or 'page'
  }}
/>
👁️ What Effect It Has
  • 'width' (Default): Automatically calculates zoom scale so document width comfortably spans the container width with minimal horizontal margins. Best for continuous vertical reading without horizontal scrolling.
  • 'page': Scales the document so that the entire height and width of a page fit within the viewport without requiring vertical scrolling for that page.
📐 Responsive Auto-Fit: ResizeObserver automatically recalculates fit scale on window or container resize.
showThumbnails boolean
Default: false
Whether the page/slide thumbnail sidebar panel is expanded by default on document load.
💻 How to Set
<FilePreview
  src={file}
  options={{
    showThumbnails: true // 👈 Opens thumbnail drawer initially
  }}
/>
👁️ What Effect It Has
  • When true: Opens the left thumbnail drawer displaying visual preview cards for all pages or slides. Users can click any thumbnail to jump to that page.
  • When false: The sidebar starts collapsed, maximizing document reading area. The user can open it by clicking the Thumbnails toolbar icon.
🖼️ Multi-page Navigation: Supported for PDF, Word, PowerPoint, RTF, and OpenDocument.
zoom number
Default: 1.0 (auto-fit width)
Initial zoom magnification factor applied to document pages, slides, sheets, or images upon opening (e.g. 1.0 for 100%, 1.5 for 150%, 0.75 for 75%).
💻 How to Set
<FilePreview
  src={file}
  options={{
    zoom: 1.5 // 👈 Starts at 150% magnification
  }}
/>
👁️ What Effect It Has
  • Magnification Factor: Directly scales page canvas, typography, images, and tables by the given multiplier (1.5 = 150% scale).
  • Overrides Auto-Fit: When specified, bypasses the automatic viewport width scaling and locks to the exact requested zoom level.
  • Toolbar Sync: Automatically updates the zoom percentage badge displayed in the toolbar.
🔍 Visual Difference: 1.5 renders the document 50% larger than baseline with high-DPI clarity.
page number
Default: 1
Initial 1-based page, slide, or sheet number to navigate to immediately when the document is rendered.
💻 How to Set
<FilePreview
  src={file}
  options={{
    page: 3 // 👈 Jumps directly to page/slide 3
  }}
/>
👁️ What Effect It Has
  • Instant Navigation: Scrolls or transitions directly to page 3 upon load without requiring the user to scroll through pages 1 and 2.
  • Deep Linking: Enables linking directly to relevant invoice pages, report appendices, or specific presentation slides.
  • Toolbar & Thumbnail Sync: The toolbar input displays 3 / Total and the 3rd card in the thumbnail drawer is marked active.
📑 Multi-page Support: Supported for PDF, Word (.docx, .doc, .rtf), PowerPoint (.pptx, .ppt), OpenDocument, and Excel sheets.
className string
Default: ''
Custom CSS class name attached to both the outer host container and the inner .fp-viewer root element. Enables custom border styling, drop shadows, responsive dimensions, and Tailwind CSS utilities. (Also accepts alias classname).
💻 How to Set
<FilePreview
  src={file}
  className="custom-viewer shadow-xl rounded-2xl"
  options={{
    className: 'custom-viewer' // Or pass inside options
  }}
/>
👁️ What Effect It Has
  • DOM Class Injection: Automatically adds the specified class string to both the host element and .fp-viewer.
  • Seamless Utility Classes: Works directly with CSS frameworks like Tailwind CSS, Bootstrap, and CSS Modules.
  • Custom Theming: Allows scoping custom CSS overrides (e.g. toolbar colors, borders, fonts) to specific viewer instances.
🎨 Custom Styling: Outer container and inner canvas inherit your application's custom CSS rules.
standaloneViewerUrl string
Default: undefined (built-in full window)
Custom destination URL navigated when the user clicks the "Open in Separate Full Window" button (↗) in the toolbar. (Also accepts alias standalloneViewerUrl).
💻 How to Set
<FilePreview
  src={fileUrl}
  options={{
    // Directs "Open in New Window" to your dedicated viewer route:
    standaloneViewerUrl: '/app/standalone-viewer.html'
  }}
/>
👁️ What Effect It Has
  • Target Route Redirection: When clicked, opens a new browser window/tab pointing to your designated URL instead of a generic blank window.
  • Automatic Query Parameters: Automatically appends mode=fullscreen, src=..., fileName=..., and transferId=... so your standalone route immediately knows which document to render.
  • Large Buffer Support: Even when previewing in-memory Blobs or File uploads, the binary data is safely synced via IndexedDB transfer keys.
↗️ Pop-out Integration: Perfect for embedded CRM/ERP portals wanting to pop out into a full-screen dedicated window.

🧩 Granular Toolbar Button Controls (ToolbarConfig)

You can keep the toolbar enabled while selectively disallowing or hiding specific buttons by passing booleans under toolbar: { ... } or directly on options.

Button / Action Option Key Default Effect When Set to false
Download (📥) download: false true Hides the download button, preventing users from downloading the raw file asset from the viewer toolbar.
Print (🖨️) print: false true Hides the print button to restrict printing from the viewer interface.
Open in Separate Window (↗️) openWindow: false true Hides the separate full window expansion button.
Thumbnails (⊞) thumbnails: false true Hides the thumbnail grid toggle icon.
Fullscreen (⛶) fullscreen: false true Hides the browser fullscreen toggle button.
Zoom In / Out (➕ / ➖) zoomIn: false, zoomOut: false true Hides the magnification increment and decrement buttons.
Fit to Width / Reset (↔ / 🔄) fitWidth: false, resetZoom: false true Hides the fit-to-width and zoom reset buttons.
Rotate CW / CCW (↻ / ↺) rotate: false (or rotateCW: false) true Hides page rotation buttons (PDF, Word, images).
Page Navigation (< [1] / N >) pageNav: false true Hides the page number input box and previous/next page chevron buttons.
Copy Text (📋) copy: false true Hides the text clipboard copy button (code, RTF, legacy documents).
Media Controls (▶, ⏸, ⏩, ⏪) play: false, speed: false, etc. true Hides playback controls for audio and video media files.
💻 Example: Disallow Download, Print & Separate Window
<FilePreview
  src={documentUrl}
  options={{
    showToolbar: true, // Keep toolbar visible
    toolbar: {
      download: false,   // 👈 Disallow downloading
      print: false,      // 👈 Disallow printing
      openWindow: false, // 👈 Disallow opening in separate window
    }
  }}
/>

📡 Events & Lifecycle Callbacks

Listen to document lifecycle events, pagination changes, and zoom updates.

Event Payload Description
onLoading ('loading') { source } Fired immediately when file parsing and rendering starts.
onLoaded ('loaded') { metadata, plugin } Fired when the document is rendered, verified, and displayed to the user.
onError ('error') Error Fired if the document is corrupt or fails to render.
onPageChange ('page-change') { page, total } Fired automatically when scrolling down past pages or navigating pages.
onZoomChange ('zoom-change') { scale } Fired whenever the user zooms in, zooms out, or auto-fits.

⚡ Imperative API & Ref Methods

Control the viewer programmatically through component refs or the viewer instance.

React Ref Example (useRef)
import { useRef } from 'react';
import { FilePreview, FilePreviewHandle } from '@file-preview-viewer/viewer/react';

export function ControlledViewer({ file }) {
  const viewerRef = useRef<FilePreviewHandle>(null);

  return (
    <div>
      <div style={{ marginBottom: 10, display: 'flex', gap: 8 }}>
        <button onClick={() => viewerRef.current?.setShowToolbar(false)}>Hide Toolbar</button>
        <button onClick={() => viewerRef.current?.setShowToolbar(true)}>Show Toolbar</button>
        <button onClick={() => viewerRef.current?.toggleToolbar()}>Toggle Toolbar</button>
        <button onClick={() => viewerRef.current?.fitToPage()}>Fit to Page</button>
        <button onClick={() => viewerRef.current?.resetZoom()}>Reset Zoom</button>
      </div>

      <FilePreview ref={viewerRef} src={file} />
    </div>
  );
}

📄 80+ Supported File Formats (15 Categories)

Zero cloud conversion, 100% private client-side rendering across all popular office, media, code, and archive extensions.

Category Extensions Engine & Features
Word Documents
.docx .docm .dotx .dotm .doc .dot
Native docx-preview & CFBF binary parser. DrawingML charts, tables, images, native pagination, automatic page-change scrolling, print, download.
PowerPoint Presentations
.pptx .pptm .ppsx .ppsm .potx .potm .ppt .pps .pot
Slide-by-slide canvas rendering, default fitMode: 'page', slide thumbnails sidebar, navigation & wheel scroll, full in-slide text search (Ctrl+F) with transparent selection layer, multi-format embedded pictures (PNG, JPEG, GIF, BMP).
Spreadsheets & Workbooks
.xlsx .xlsm .xls .xlsb .xltx .xltm .ods
Multi-sheet workbook tabs, cell formatting, formula evaluation, column resizing, sheet thumbnails, print, download.
PDF Documents
.pdf
Continuous lazy-loading multi-page viewer, text layer selection, search highlights, automatic page scroll tracking, CW/CCW rotation, thumbnail jumping.
Emails & Messages
.eml .msg
RFC 822/2822 emails & Outlook binary messages with formatted sender/recipient headers, avatar chip, sanitized HTML body, inline CID images, and one-click attachment downloads.
OpenDocument Suite
.odt .ott .odp .otp .ods .odg .odf
Native OpenDocument ODF XML text, tables, embedded charts, continuous multi-page scrolling layout, print, download.
Rich Text & HTML
.rtf .html .htm .xhtml
Native RTF parser with font formatting and embedded images, sandboxed iframe HTML preview with DOMPurify sanitization.
Rich Markdown
.md .markdown .mdown .mkd
GitHub Flavored Markdown (tables, task checklists, blockquotes), syntax-highlighted code blocks, copy markdown, print, download.
Data & Tables
.csv .tsv
Interactive paginated data grid, auto delimiter detection (comma/tab), column sorting, header styling, print, download.
ZIP Archives
.zip
Hierarchical file tree & detail table, real-time search filtering, individual file extraction and direct download, full zip download.
3D Models
.stl .obj
Three.js interactive 360° orbit controls, perspective camera, ambient & directional lighting, solid vs wireframe toggle, reset view.
Images & Vector
.jpg .jpeg .png .gif .webp .svg .bmp .ico .tiff .tif .avif .apng .jfif .pjpeg .pjp
Smooth pan & zoom, rotate 90° CW/CCW, SVG DOM sanitization with DOMPurify, reset view, print, download.
Video Media
.mp4 .m4v .webm .ogv .ogg .mov .avi .mkv .flv .wmv .3gp .mpg .mpeg
Responsive HTML5 video player, play/pause, seek bar, volume/mute, video rotation, fullscreen support, download.
Audio Media
.mp3 .wav .ogg .flac .aac .m4a .wma .opus .weba
Centered player card, Web Audio API waveform visualizer, audio playback controls, time display, download.
Code & Text (190+ Languages)
.ts .tsx .js .jsx .mjs .cjs .json .jsonc .json5 .html .css .scss .sass .less .py .pyw .java .c .cpp .cc .h .hpp .cs .go .rs .sql .php .rb .swift .kt .scala .r .lua .sh .bash .zsh .fish .bat .cmd .ps1 .yaml .yml .toml .xml .txt .log .ini .cfg .env .dockerfile .graphql .proto .diff .patch
190+ languages syntax highlighting via highlight.js, line numbers gutter, clean text copy (excluding line numbers), code search, font zoom in/out, print, download.