Getting started

Installation and first render

Two minutes from an empty project to a Word document on screen, with no build configuration and no server.

Install

One package is enough. It pulls in the facade, the parsers and the renderers as ordinary dependencies — all of them first-party, none of them with dependencies of their own.

npm install @apertura/react

Render a document

file accepts a File from an input, a Blob, a byte buffer, or a URL string. The format is detected from the bytes rather than from the file extension, so a mislabelled file still opens.

App.tsx

import { DocumentViewer } from '@apertura/react';
import { useState } from 'react';

export function App() {
  const [file, setFile] = useState<File>();

  return (
    <div style={{ height: '100vh', display: 'grid', gridTemplateRows: 'auto 1fr' }}>
      <input
        type="file"
        accept=".docx,.xlsx,.pptx"
        onChange={(event) => setFile(event.target.files?.[0])}
      />
      <DocumentViewer file={file} fit="width" />
    </div>
  );
}

Give it a height

The viewer fills its container, and a container with no height renders nothing. This is the single most common thing to get wrong on the first try.

Server-side rendering

The renderer measures real line boxes to paginate, so it needs a layout engine and has nothing to do on the server. Under Next.js, Nuxt or Remix, load it in the browser only:

viewer.tsx

'use client';

import dynamic from 'next/dynamic';

const DocumentViewer = dynamic(
  () => import('@apertura/react').then((m) => ({ default: m.DocumentViewer })),
  { ssr: false },
);

Keeping the bundle small

The default registry includes every format. When an application only ever shows one, build the registry by hand and the other parsers never enter the bundle:

registry.ts

import { FormatRegistry } from '@apertura/core';
import { docxParser } from '@apertura/docx';
import { docxView } from '@apertura/docx-view';

export const registry = new FormatRegistry()
  .registerParser(docxParser)
  .registerView(docxView);

// Then: <DocumentViewer file={file} registry={registry} />

Next steps

React — the hook underneath the component, page navigation, zoom and outline.
Theming — the CSS custom properties the renderers read.
Licensing — when a key is needed and how it is verified offline.