API reference

@apertura/react

React bindings for the Apertura viewer

8 exported symbols · 2 declared here · 6 re-exported

Classes

Viewerfrom @apertura/viewer

class Viewer

A framework-independent document viewer. The single place that knows the full path from bytes to format to document to DOM. The React, Vue and Angular wrappers are thin adapters over this class, so their behaviour is identical by construction rather than by convention.

state

ViewerState

container

HTMLElement

view

DocumentView | undefined

The live view, for reaching format-specific APIs such as page navigation.

(listener: (state: ViewerState) => void) => () => void

Subscribes to state changes. Returns an unsubscribe function.

open

(input: ByteSourceInput, options?: ViewerOptions) => Promise<void>

Opens a file and mounts its view. Calling it again before the previous call settles is correct: the older result is discarded. That is the normal case when a user picks files in quick succession.

refresh

() => void

Re-renders the current view.

() => void

Closes the document and clears the container.

destroy

() => void

Releases every resource. The instance must not be used afterwards.

Functions

createDefaultRegistryfrom @apertura/viewer

function createDefaultRegistry(): FormatRegistry

A registry with every supported format registered. The convenient entry point for an application that just needs to open a file. When bundle size matters, build a {@link FormatRegistry} by hand so only the parsers actually used are included.

createViewerfrom @apertura/viewer

function createViewer(container: HTMLElement, options?: ViewerOptions): Viewer

Creates a viewer mounted into the given element.

useApertura

function useApertura(options?: ViewerOptions): UseAperturaResult

Binds a {@link Viewer} to a React component's lifecycle. State is read through `useSyncExternalStore`: the viewer is the external source of truth, and subscribing to it directly avoids duplicating state in `useState` and avoids tearing under concurrent rendering.

Interfaces

UseAperturaResult

interface UseAperturaResult

containerRef

(element: HTMLElement | null) => void

Attach this ref to the element the document should be mounted into.

state

ViewerState

open

(input: ByteSourceInput) => Promise<void>

() => void

viewer

Viewer | undefined

Direct access to the viewer, for cases the hook does not cover.

ViewerOptionsfrom @apertura/viewer

interface ViewerOptions extends ViewOptions, OpenOptions

registry?

FormatRegistry | undefined

The plugin set to use. Defaults to every supported format. Pass a custom registry to keep unused parsers out of the bundle.

renderOptions?

Record<string, unknown> | undefined

Extra options forwarded to the format renderer.

ViewerStatefrom @apertura/viewer

interface ViewerState

status

ViewerStatus

document

AperturaDocument | undefined

detection

DetectionResult | undefined

error

Error | undefined

progress

number

Parse progress, 0..1.

Type aliases

ViewerStatusfrom @apertura/viewer

type ViewerStatus = 'idle' | 'loading' | 'ready' | 'error'

Viewer state; UI wrappers render indicators from it.