Component Options

Minimal Options Shape

Standard component packages stay lightweight. Install a component package for your stack, then assemble concrete file-format capability through options.preset or options.renderers.

import officePreset from '@file-viewer/preset-office'

export const viewerOptions = {
  preset: officePreset,
  rendererMode: 'replace',
  theme: 'light',
  styleIsolation: 'shadow',
  ui: {
    density: 'compact'
  },
  toolbar: {
    position: 'bottom-right',
    download: true,
    print: true,
    exportHtml: true,
    zoom: true
  },
  watermark: {
    text: 'Internal',
    opacity: 0.14
  },
  search: {
    maxMatches: 1000,
    caseSensitive: false
  },
  archive: {
    cache: true,
    workerTimeoutMs: 30000,
    entryActions: {
      download(entry) {
        return entry.path.startsWith('public/')
      }
    }
  },
  pdf: {
    toolbar: true,
    streaming: 'same-origin'
  }
}

builtinRenderers remains available for advanced baseline control and historical compatibility, but normal integrations should start with preset or renderers.

Preflight Before Rendering

Call precheckFileViewerSource() after file selection when the product must reject an unsupported or obviously malformed file before mounting a viewer. It checks extension capability and validates known PDF, OpenXML / OpenDocument, legacy OLE Office, and RTF signatures or package parts without loading a renderer.

import { precheckFileViewerSource } from '@file-viewer/core/headless'

const result = await precheckFileViewerSource(file, {
  supportedExtensions: ['pdf', 'docx', 'xlsx', 'pptx']
})

if (!result.previewable) {
  console.warn(result.status, result.reason, result.missingParts)
}

supported describes the supplied capability list; valid describes the content check. valid: null means the format has no lightweight validator or only a URL was supplied, not that a full parse passed. The renderer remains the final authority for malformed content. Blob-backed ZIP/Office files read only ZIP metadata instead of copying the complete file.

Common Options

Preset And Renderer Matrix

Presets are product-shaped capability bundles. Individual renderers are exact, minimal imports for products that only need a few formats.

Every renderer below can be passed through options.renderers:

EML and MSG attachments open through the same resolved renderer registry as the parent viewer. React, React Legacy, Vanilla JS, and Web Component integrations do not need a framework-specific nested-preview bridge. With a lightweight component, include the preset or renderer for each attachment type you want to preview (for example, the PDF renderer for PDF attachments); Full packages already include the complete standard registry. Attachment filenames are rendered as text, not HTML.

@file-viewer/eda-layout, @file-viewer/eda-orcad, @file-viewer/geometry-engine, and @file-viewer/pptx are reusable engine packages behind renderers. Advanced teams can use them directly, while normal viewer integrations should install the matching renderer or preset.

Assembly Decisions

Renderer-specific Options

Operation Guard

const options = {
  async beforeOperation(context) {
    if (context.operation === 'download') {
      return await checkPermission(context.source)
    }
    return true
  },
  toolbar: {
    position: 'bottom-right',
    items: {
      'zoom-reset': false
    },
    permissions: {
      print: canPrint
    }
  }
}

Built-in operation keys are download, print, export-html, zoom-in, zoom-out, and zoom-reset. toolbar.items only controls the built-in toolbar UI, so teams can replace selected buttons with their own native controls. toolbar.permissions is a hard gate: a false value blocks both the built-in toolbar and direct controller / ref API calls before custom beforeOperation hooks run. Returning false from any guard cancels the operation.

Print delivery notes:

• printRenderedHtml() prints the full rendered document and keeps the current watermark when options.watermark is enabled.
• printWithMask() opens the page-aware mask and stamp designer. It can draw black cover regions or upload a local PNG, JPEG, WebP, GIF, or SVG stamp, then move, resize, remove, and print it under the watermark. Uploaded files stay in the browser as data URLs. The designer is loaded asynchronously inside core, so installing a component package is enough—no extra subpath alias is required.
• Custom toolbars can call either API directly; printRenderedHtml({ mask }) also accepts precomputed regions and stamps. Stamp geometry uses percent left, top, width, and height, with optional pageIndex, opacity, rotate, and alt fields.
• Export / print HTML inlines ephemeral blob: image URLs as portable data: URLs, so DOCX figures remain visible after download or in the print window.
• CAD export captures the current camera view / current native DWF page, including WebGL vectors and text overlays. Source mode uses a dark background and adaptive contrast; monochrome uses black lines on white paper. Explicit background options take priority. The native PNG/JPEG downloads retain text/image watermarks, use the owning viewer's download hooks, and require both download and HTML-export permissions. cad.showImageExport: false hides those buttons. HTML embeds the PNG and Print supports Save as PDF. Use Fit before exporting a whole drawing; this is not a multi-sheet vector PDF converter.

Component teardown follows the host framework lifecycle. Vue 3 / Vue 2 component unmount, React unmount, Web Component disconnectedCallback, Svelte action destroy, and jQuery plugin destroy all enter the same controller teardown path: active loading is cancelled, the renderer session is destroyed, rendered DOM is cleared, zoom/search/view-state observers are stopped, and unload-start / unload-complete fire with reason: "component-unmount". In Element Plus el-dialog destroy-on-close, route switches, tab closing, or v-if removal, host code does not need to clear the viewer container manually.

When the host only hides the viewer, such as v-show, a dialog without destroy-on-close, or KeepAlive, the active document remains mounted. Use this when preserving reading position is desired. If the product needs explicit teardown while keeping the surrounding component alive, call destroy() on the component ref or controller, then recreate the viewer before previewing again.

Lifecycle Hooks

const options = {
  hooks: {
    onLoadStart(context) {
      console.log('loading', context.type, context.filename)
    },
    onLoadComplete(context) {
      console.log('loaded', context.rendererId, context.duration)
    },
    onUnloadStart(context) {
      console.log('unloading', context.reason)
    },
    onUnloadComplete(context) {
      console.log('unloaded', context.filename)
    }
  }
}

Toolbar Customization

Framework packages expose the same operation model with ecosystem-native customization:

Toolbar buttons should call viewer operations rather than wrapping rendered content with outer CSS transforms. This keeps spreadsheet coordinates, PDF text layers, CAD canvases, and mobile gestures aligned.

The initial zoom label is not assumed to be 100%. Renderers report the actual scale after first-screen fit, image natural-size loading, PDF / Word layout, container resize, or any internal reflow. Built-in toolbars and getOperationAvailability() use the same state to keep zoomIn, zoomOut, and zoomReset accurate. Custom toolbars should sync from zoom-change or getZoomState() instead of caching their own default percentage.

The percentage baseline follows the renderer's coordinate system. For Word/DOCX, 100% is the document page's natural CSS size, so 120% means the layout width multiplied by 1.2, not the current fit-width result enlarged by another 20%; a mobile fit can therefore start below 100%. CAD has no useful cross-file CSS physical size, so its 100% is the most recent fitted camera view and later buttons, wheel input, or pinch gestures report a ratio relative to that view. Do not convert percentages across formats into a paper-scale measurement.

View State Sync

initialViewState, view-state-change, getViewState(), and applyViewState() are designed for projection systems, remote-control displays, side-by-side comparison, and reading-position restore. Every standard renderer path registers a view-state provider. Renderers without a dedicated provider use the generic DOM provider, which records the renderer id, current zoom, and scroll ratios. PDF adds page, page count, rotation, and navigation state. XMind adds sheet index, panX, panY, and zoom. Geo adds map center, zoom, bearing, and pitch. 3D adds camera position, target, and display options. CAD reports the view snapshot exposed by the underlying CAD viewer.

let lastState = null

const options = {
  initialViewState: {
    page: 3,
    scale: 1.25,
    scroll: { topRatio: 0.18 }
  }
}

function onEvent(event) {
  if (event.type === 'view-state-change') {
    lastState = event.payload.state
    sendToDisplay(event.payload)
  }
}

await displayViewer.applyViewState(lastState, {
  source: 'api',
  action: 'restore'
})

A custom PDF toolbar can read the page snapshot and apply a partial state for previous, next, or page-input navigation:

const state = viewerRef.value?.getViewState()
const page = Number(pageInput.value)

await viewerRef.value?.applyViewState(
  { page },
  { source: 'api', action: 'page-change' }
)

await viewerRef.value?.applyViewState(
  { page: Math.min((state?.page || 1) + 1, state?.pageCount || 1) },
  { source: 'api', action: 'page-step' }
)

For synchronization, send the full state snapshot instead of replaying individual button clicks. PDF page changes, zooming, scrolling, XMind panning, Geo map movement, and 3D camera updates all use the same event shape; the display side only needs to call applyViewState(). High-frequency projection updates may be coalesced to one snapshot per animation frame, but do not use a trailing-only debounce that waits until scrolling stops.

Use pdf.bbox to highlight and focus a region on first load, or replace/clear it dynamically through applyViewState(). Pages are one-based. OCR pixel coordinates use pixel plus the source image dimensions. Native PDF coordinates use pdf-point and default to a bottom-left origin. ratio and percent default to a top-left origin. A single box or an array is accepted, and highlights stay attached through zoom and rotation.

const options = {
  pdf: {
    bbox: {
      page: 3,
      x: 120,
      y: 240,
      width: 360,
      height: 64,
      unit: 'pixel',
      sourceWidth: 1440,
      sourceHeight: 2036,
      label: 'Contract amount'
    }
  }
}

await viewer.applyViewState({
  page: 5,
  extra: {
    bbox: { page: 5, x: 72, y: 640, width: 220, height: 36, unit: 'pdf-point' }
  }
}, { source: 'api', action: 'bbox-focus' })

await viewer.applyViewState(
  { extra: { bbox: null } },
  { source: 'api', action: 'bbox-clear' }
)

PDF default assets are probed from the site root (/vendor/pdf/...) so Vue Router, React Router, and other deep routes do not accidentally request vendor/pdf/pdf.worker.mjs from the current page path. When the static worker is missing or an app server falls back to HTML, the PDF renderer lazy-loads the packaged PDF.js worker handler as a compatibility fallback. Use absolute pdf.workerUrl, pdf.cMapUrl, pdf.wasmUrl, and pdf.standardFontDataUrl when deploying under a sub-path, a dedicated static asset domain, or a strict CSP. PPTX uses the @file-viewer/pptx worker on demand; set presentation.workerUrl and, when necessary, presentation.workerType for custom worker routes. Binary .ppt uses @file-viewer/[email protected]; standard distributions keep its verified ESM/Worker/WASM/font files together under vendor/ppt/. Configure presentation.pptModuleUrl, pptWorkerUrl, pptWasmUrl, and pptFontUrl only for a custom layout.