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.
📦 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 i @file-preview-viewer/viewer
pnpm add @file-preview-viewer/viewer
yarn add @file-preview-viewer/viewer
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.
<FilePreview
src={file}
options={{
showToolbar: false // 👈 Hides toolbar completely
}}
/>
- 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)orviewer.toggleToolbar()without reloading the file.
true renders the 40px action toolbar; false collapses it to 0px.
<FilePreview
src={file}
options={{
showFileName: false // 👈 Hides top title bar
}}
/>
- When
true: Displays a sleek header bar above the toolbar with📄 FileName.extand a colored badge such asDOCX,PDF, orXLSX. - When
false: Completely hides the title header bar, useful when your page already provides its own heading or tab title.
📄 Repository.xlsx [XLSX]
<FilePreview
src={blobData}
options={{
fileName: 'Annual_Financial_Report_2026.xlsx'
}}
/>
- 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.
blob:http...
<FilePreview
src={file}
options={{
theme: 'dark' // 'light' | 'dark' | 'auto'
}}
/>
'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 viaprefers-color-schememedia query.
<FilePreview
src={file}
options={{
toolbarPosition: 'bottom' // 👈 Places toolbar at bottom
}}
/>
'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.
.fp-toolbar-container and document viewport.
<FilePreview
src={file}
options={{
fitMode: 'page' // 'width' (default) or 'page'
}}
/>
'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.
<FilePreview
src={file}
options={{
showThumbnails: true // 👈 Opens thumbnail drawer initially
}}
/>
- 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.
1.0 for 100%, 1.5 for 150%, 0.75 for 75%).
<FilePreview
src={file}
options={{
zoom: 1.5 // 👈 Starts at 150% magnification
}}
/>
- 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.
1.5 renders the document 50% larger than baseline with high-DPI clarity.
<FilePreview
src={file}
options={{
page: 3 // 👈 Jumps directly to page/slide 3
}}
/>
- 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 / Totaland the 3rd card in the thumbnail drawer is marked active.
.fp-viewer root element. Enables custom border styling, drop shadows, responsive dimensions, and Tailwind CSS utilities. (Also accepts alias classname).
<FilePreview
src={file}
className="custom-viewer shadow-xl rounded-2xl"
options={{
className: 'custom-viewer' // Or pass inside options
}}
/>
- 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.
↗) in the toolbar. (Also accepts alias standalloneViewerUrl).
<FilePreview
src={fileUrl}
options={{
// Directs "Open in New Window" to your dedicated viewer route:
standaloneViewerUrl: '/app/standalone-viewer.html'
}}
/>
- 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=..., andtransferId=...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.
🧩 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. |
| Search / Find (Ctrl+F) (🔍) | search: false |
true |
Hides the in-document search button and disables the built-in search bar. |
| 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. |
<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.
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. |