@polyrender/react

React component and hook for rendering documents in the browser. A thin wrapper around @polyrender/core that handles React lifecycle, cleanup, and ref-based imperative control.

Supports PDF, EPUB, DOCX, ODT, ODS, CSV/TSV, source code, plain text, and comic book archives (.cbz, .cbr, .cb7, .cbt).

Installation

npm install @polyrender/react @polyrender/core

Install peer dependencies only for the formats you need:

npm install pdfjs-dist       # PDF
npm install epubjs           # EPUB
npm install docx-preview     # DOCX
npm install jszip            # ODT, CBZ comic archives
npm install xlsx             # ODS
npm install papaparse        # CSV/TSV
npm install highlight.js     # Code, Markdown, JSON, XML/HTML

# Comic book archives — additional optional backends:
npm install node-unrar-js    # CBR (.cbr, RAR-compressed comics)
npm install 7z-wasm          # CB7 (.cb7, 7-Zip-compressed comics)

# Comic book archives — optional exotic image format decoders:
npm install @jsquash/jxl     # JPEG XL images inside archives
npm install utif             # TIFF images inside archives

Quick Start

import { DocumentViewer } from '@polyrender/react'
import '@polyrender/core/styles.css'

function App() {
  return (
    <DocumentViewer
      source={{ type: 'url', url: '/report.pdf' }}
      theme="dark"
      style={{ width: '100%', height: '80vh' }}
      onReady={(info) => console.log(`${info.pageCount} pages`)}
      onPageChange={(page, total) => console.log(`${page}/${total}`)}
    />
  )
}

<DocumentViewer>

Drop-in component. Props mirror PolyRenderOptions from @polyrender/core.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | source | DocumentSource \| null | — | The document to render | | format | DocumentFormat | auto | Override format detection | | theme | 'dark' \| 'light' \| 'system' | 'dark' | Color theme | | className | string | — | Extra CSS class on the root element | | style | React.CSSProperties | — | Styles for the wrapper div (set width/height here) | | initialPage | number | 1 | Starting page | | zoom | number \| 'fit-width' \| 'fit-page' \| 'auto' | — | Initial zoom | | toolbar | boolean \| ToolbarConfig | true | Toolbar visibility/config. ToolbarConfig fields: navigation, zoom, wrapToggle, fullscreen, info, download, position | | showPageNumbers | boolean | — | Show page numbers | | onReady | (info: DocumentInfo) => void | — | Fired when document is loaded | | onPageChange | (page, total) => void | — | Fired on page navigation | | onZoomChange | (zoom: number) => void | — | Fired on zoom change | | onError | (error: PolyRenderError) => void | — | Fired on unrecoverable error | | onLoadingChange | (loading: boolean) => void | — | Fired on loading state change | | pdf | PdfOptions | — | PDF-specific options | | epub | EpubOptions | — | EPUB-specific options | | code | CodeOptions | — | Code-specific options | | csv | CsvOptions | — | CSV/TSV-specific options | | comic | ComicOptions | — | Comic archive options (JXL/TIFF decoders, format filter) |

Imperative Control via Ref

import { useRef } from 'react'
import { DocumentViewer, type DocumentViewerRef } from '@polyrender/react'
import '@polyrender/core/styles.css'

function App() {
  const viewerRef = useRef<DocumentViewerRef>(null)

  return (
    <>
      <DocumentViewer
        ref={viewerRef}
        source={{ type: 'url', url: '/report.pdf' }}
        style={{ width: '100%', height: '80vh' }}
      />
      <button onClick={() => viewerRef.current?.goToPage(1)}>First page</button>
      <button onClick={() => viewerRef.current?.setZoom('fit-width')}>Fit width</button>
    </>
  )
}

DocumentViewerRef exposes: goToPage(page), setZoom(zoom), getCurrentPage(), getPageCount(), getZoom().

useDocumentRenderer (headless hook)

For building fully custom UI around the renderer:

import { useDocumentRenderer } from '@polyrender/react'
import '@polyrender/core/styles.css'

function CustomViewer({ url }: { url: string }) {
  const { containerRef, state, goToPage, setZoom } = useDocumentRenderer({
    source: { type: 'url', url },
    theme: 'dark',
    toolbar: false,
  })

  return (
    <div>
      <div ref={containerRef} style={{ width: '100%', height: '600px' }} />
      <div>
        <button onClick={() => goToPage(state.currentPage - 1)}>Prev</button>
        <span>{state.currentPage} / {state.totalPages}</span>
        <button onClick={() => goToPage(state.currentPage + 1)}>Next</button>
        <button onClick={() => setZoom(state.zoom * 1.2)}>Zoom In</button>
      </div>
    </div>
  )
}

Return value

| Field | Type | Description | |-------|------|-------------| | containerRef | RefObject<HTMLDivElement> | Attach to your container element | | state | PolyRenderState | Current viewer state | | goToPage | (page: number) => void | Navigate to a page | | setZoom | (zoom) => void | Set zoom level | | ready | boolean | true after onReady fires | | error | PolyRenderError \| null | Current error, if any |

PolyRenderState contains: loading, error, currentPage, totalPages, zoom, documentInfo.

Document Sources

See @polyrender/core for full documentation on FileSource, UrlSource, PagesSource, and ChunkedSource.

Theming

Import and apply styles from @polyrender/core:

import '@polyrender/core/styles.css'

Override CSS custom properties on the .polyrender root element:

.my-viewer .polyrender {
  --dv-bg: #1e1e2e;
  --dv-text: #cdd6f4;
  --dv-accent: #89b4fa;
}

Repository

The source code is hosted in two locations:

• Tangled (primary): https://tangled.org/aria.pds.witchcraft.systems/polyrender
• GitHub (mirror): https://github.com/BuyMyMojo/polyrender

This package lives under packages/react in the monorepo.

License

Zlib