@dukeofwest/universal-file-preview
v0.5.0
Published
Zero-dependency browser previews for DOCX, XLSX, PPTX, OpenDocument text, spreadsheets and presentations, and images, in TypeScript. Optional Web Worker parsing, strict Content Security Policy and Trusted Types support.
Maintainers
Keywords
Readme
Universal File Preview
Open the live Angular, React and Vue demo — try a framework integration with your own file or download a sample document.
Browser-based TypeScript previews for common image formats and selected content from DOCX, XLSX, PPTX, and OpenDocument spreadsheet (ODS), text (ODT) and presentation (ODP) files. The library provides file loading, format detection, a typed viewer lifecycle, and a renderer registry. Its ZIP, DEFLATE, XML, document parsing, and rendering code is implemented in this project; it does not depend on third-party document parsing or rendering packages.
Features
- Preview GIF, PNG, JPEG, WebP, and sanitized SVG using browser image decoding.
- Render implemented subsets of DOCX, XLSX, PPTX, ODS/OTS/FODS, ODT/OTT/FODT and ODP/OTP/FODP in the browser.
- Load from a
File/Blob,ArrayBuffer,Uint8Array, or a URL fetched by the browser. - Replace the current file, zoom or fit the preview, download loaded bytes, and clean up renderer resources.
- Add format handlers through a renderer registry.
- Apply default viewer styles inside the viewer root; optionally import the package CSS entry.
- Limit file size, ZIP entry size and count, and XML size, reject unsafe ZIP paths, and return typed preview errors.
The supported-format matrix lists what is detected, parsed, rendered, and covered by automated tests. The Office renderers are partial implementations and do not claim pixel-perfect compatibility with Microsoft Office.
Quick start
Install the package with npm install @dukeofwest/universal-file-preview as described in Installation. The following example uses a browser file input and the public FilePreviewer API:
import { FilePreviewer } from "@dukeofwest/universal-file-preview";
const container = document.querySelector<HTMLElement>("#viewer");
const input = document.querySelector<HTMLInputElement>("#file");
if (!container || !input) throw new Error("Viewer elements are missing.");
const preview = new FilePreviewer({
container,
file: { name: "welcome.svg", source: new Blob(["<svg></svg>"], { type: "image/svg+xml" }) },
});
await preview.open();
input.addEventListener("change", async () => {
const file = input.files?.[0];
if (!file) return;
try {
await preview.load({ name: file.name, source: file, mimeType: file.type });
} catch (error) {
console.error("Could not preview file", error);
}
});
Call preview.destroy() from the owning UI's cleanup hook when the viewer is removed.
See Getting started for remote files, byte buffers, error handling, switching files, and custom renderers.
Angular, React and Vue
The framework examples are independent applications that consume the published npm package. They do not import the library source or add document-rendering dependencies. Each example uses a framework-managed element as the viewer container, passes a browser File to FilePreviewer, handles rejected loads, and calls destroy() when the viewer is cleared or the component is removed. Import the optional package stylesheet with @dukeofwest/universal-file-preview/styles.css.
Install the package in the framework application:
npm install @dukeofwest/universal-file-previewThe public integration shape is the same in each framework:
import { FilePreviewer } from "@dukeofwest/universal-file-preview";
const preview = new FilePreviewer({
container: previewElement,
file: { name: file.name, source: file, mimeType: file.type },
});
await preview.open();
// On clear, replacement, or component teardown:
preview.destroy();In Angular, call this from a standalone component and destroy the instance in ngOnDestroy. In React, keep the host and instance in refs and destroy it from effect cleanup. In Vue 3, keep the instance in a shallowRef and destroy it in onBeforeUnmount. Catch errors from open() or load(); the viewer also displays its own loading and error status.
Angular quick start
import { Component, ElementRef, OnDestroy, ViewChild } from "@angular/core";
import { FilePreviewer } from "@dukeofwest/universal-file-preview";
@Component({ standalone: true, template: `<div #host></div>` })
export class PreviewComponent implements OnDestroy {
@ViewChild("host", { static: true }) host!: ElementRef<HTMLDivElement>;
private preview: FilePreviewer | null = null;
async openFile(file: File): Promise<void> {
this.preview?.destroy();
this.preview = new FilePreviewer({ container: this.host.nativeElement, file: { name: file.name, source: file, mimeType: file.type } });
try { await this.preview.open(); } catch (error: unknown) { console.error("Preview failed", error); }
}
ngOnDestroy(): void { this.preview?.destroy(); }
}React quick start
import { useEffect, useRef } from "react";
import { FilePreviewer } from "@dukeofwest/universal-file-preview";
function Preview() {
const host = useRef<HTMLDivElement>(null);
const preview = useRef<FilePreviewer | null>(null);
useEffect(() => () => preview.current?.destroy(), []);
async function openFile(file: File): Promise<void> {
const container = host.current;
if (!container) return;
preview.current?.destroy();
const instance = new FilePreviewer({ container, file: { name: file.name, source: file, mimeType: file.type } });
preview.current = instance;
try { await instance.open(); } catch (error: unknown) { console.error("Preview failed", error); }
}
return <div ref={host} />;
}Vue 3 quick start
import { onBeforeUnmount, ref, shallowRef } from "vue";
import { FilePreviewer } from "@dukeofwest/universal-file-preview";
const host = ref<HTMLDivElement | null>(null);
const preview = shallowRef<FilePreviewer | null>(null);
onBeforeUnmount(() => preview.value?.destroy());
async function openFile(file: File): Promise<void> {
const container = host.value;
if (!container) return;
preview.value?.destroy();
const instance = new FilePreviewer({ container, file: { name: file.name, source: file, mimeType: file.type } });
preview.value = instance;
try { await instance.open(); } catch (error: unknown) { console.error("Preview failed", error); }
}- Angular example and run instructions
- React example and run instructions
- Vue example and run instructions
- Framework integration guide
These are integration examples, not official framework adapter packages. See format support for the actual renderer coverage and limitations.
Try the demo
The framework demo selector hosts the actual Angular, React, and Vue applications at dukeofwest.github.io/universal-file-preview. The live site includes downloadable sample files so you can try each example without preparing your own documents.
The existing local library demo can still be run from a repository checkout:
npm ci
npm run build
npm run demoThen open http://127.0.0.1:4173/ and choose an image, DOCX, XLSX, PPTX, ODS, FODS, ODT, FODT, ODP, or FODP file.
See live demo and Pages setup for deployment status and the local framework site preview instructions.
Supported formats
| Format | Current implementation | | --- | --- | | GIF, PNG, JPEG/JPG, WebP | Browser-native image decoding; SVG is sanitized before image decoding. | | DOCX | Partial Word text, styles, tables, numbering, headers/footers, page setup, and selected images/drawings. No automatic pagination. | | XLSX | Styled worksheet grid with many cell, number, drawing, conditional-format, table, and slicer features. Charts and many formulas are not supported. | | ODS, OTS, FODS | OpenDocument spreadsheets in the same worksheet grid: typed values with the producer's saved display text, styles, number formats, merges, hidden data, comments, links, and saved view settings. Formulas are not recalculated; charts, images, and conditional formatting are not shown, and a notice lists what is missing. | | PPTX | Slide text, layout/theme/master content, shapes, images, tables, backgrounds, and navigation, with Office fidelity gaps. | | PDF, DOC, XLS, PPT | Detection only. No built-in parser or renderer. |
For detailed coverage, test status, and limitations, see Supported formats.
API and configuration
The main entry point is FilePreviewer. Its options include container, file, toolbar, zoom, download, maxFileSize, and registry. The viewer exposes open(), load(file), setZoom(value), fitToWidth(), fitToPage(), and destroy(). See API reference for public exports and exact types.
The package injects its scoped styles by default. Import @dukeofwest/universal-file-preview/styles.css when the prefixed stylesheet classes are also needed outside the viewer root.
Architecture
The flow is file source → bounded byte loading → signature/metadata detection → format parser → typed document model → registered renderer → DOM/SVG output. FilePreviewer owns the lifecycle and common controls. The ZIP/DEFLATE reader and XML parser are project code; image codecs and DOM/fetch APIs are supplied by the browser. See Architecture.
Browser requirements and framework compatibility
This is a browser package and uses browser DOM, Blob, URL.createObjectURL, fetch, and related APIs. The emitted JavaScript target is ES2022. The project does not yet publish a tested browser-version compatibility matrix. Development CI currently uses Node.js 22; a minimum supported development Node version has not been declared.
The public API is framework-agnostic. The repository includes tested Angular, React, and Vue integration examples, but does not publish framework-specific adapter packages. Use the browser lifecycle API from your framework's mount and cleanup hooks. The examples build against the current published package version.
Security and privacy
Local file sources are read in the browser and are not uploaded by this library. URL sources are fetched by the browser and remain subject to CORS and your application’s network policies. SVG, including SVG embedded in Office files, is restricted to an allowlist; external OOXML relationships are not followed. Inputs, decompression, calculation, images, and the parsed document have size and work limits. By default, document parsing runs on the main thread, so a large or crafted file can make the page unresponsive for several seconds; the optional worker mode parses documents in a Web Worker with a timeout instead. Read Security, including its deployment guidance, before previewing untrusted files.
Limitations
- DOCX, XLSX, PPTX, ODS, ODT and ODP are partial implementations; visual and feature fidelity varies by file.
- OpenDocument drawings (
.odg), charts, formulas and databases are not supported. - There is no built-in PDF or legacy binary Office renderer.
- Browser rendering and real-file visual comparisons are not covered by the current automated test suite.
- Remote resources require CORS permission. ZIP64 and encrypted OOXML and OpenDocument packages are unsupported.
- Font availability and image decoding depend on the browser and host system.
See Troubleshooting and Supported formats.
Development and validation
npm ci
npm run build
npm test
npm run typecheck
npm pack --dry-runTests use Node’s built-in test runner and synthetic parser fixtures. TypeScript is a development-only dependency; there are no runtime dependencies. See Development and Testing.
Contributing
Read CONTRIBUTING.md before making changes. The implementation must continue using the project’s own document parsing and rendering engine; do not add third-party document parsers or renderers.
License
MIT. See LICENSE.
Documentation
- Installation
- Getting started and examples
- Adoption and technical content plan
- Demo deployment
- Framework integrations
- Live framework demo
- API reference
- Supported formats
- Architecture
- Security
- Troubleshooting
- Development and testing
- Release and publishing
