import { DocViewer } from '@p10node/office-engine'
<DocViewer src={file} style={{ height: 600 }} /> // File | Blob | ArrayBuffer | Uint8Array
<DocViewer src="https://cdn.example.com/report.xlsx" /> // URL → Range requests
<DocViewer src={url} headers={{ Authorization: `Bearer ${t}` }} credentials="include" />
<DocViewer src={file} editable onSave={(blob, name) => upload(blob, name)} /> // editing
<DocViewer src={file} allowSave={false} allowDownload={false} /> // no Save/Download, no image download
<DocViewer src={file} fileMenu={false} /> // no File menu
<DocViewer src={file} theme="dark" /> // dark chrome; "auto" follows the OS setting| Item | DOCX | XLSX | PPTX |
|---|---|---|---|
| New | blank document | blank spreadsheet | blank presentation |
Open… (Ctrl+O) |
any supported file | any supported file | any supported file |
| Import CSV into new sheet | – | .csv / .tsv |
– |
Save (Ctrl+S) |
✓ | ✓ | ✓ |
| Rename… | ✓ | ✓ | ✓ |
| Download as (native) | .docx |
.xlsx |
.pptx |
| pages as shown | current sheet, fit to width | one slide per page | |
| Web page | .html, images inlined |
.html |
.html, images inlined |
| Text | .txt, .md |
.csv, .tsv (current sheet) |
.txt (incl. notes) |
| Document details | pages, words, characters | sheets, used range | slides, slide size |
Print (Ctrl+P) |
✓ | ✓ | ✓ |
| Host items, Close | fileMenuItems, onClose |
fileMenuItems, onClose |
fileMenuItems, onClose |
Open converts other formats: .csv / .tsv → workbook, .txt / .md / .html → document (headings, lists, bold / italic, links), .mmd / .puml / .dot / .gv → document with the drawing. Converted files start unsaved; Save writes the Office file.
New / Open replace the shown document until the host passes another src (unsaved changes are confirmed first; both are hidden during collaboration).
Rename changes the shown name and the name used by Save / Download (onRename receives it); it does not reload the document.
Document details also lists the file's core properties (title, author, created, modified…).
PDF goes through the browser print dialog ("Save as PDF"), so text stays selectable. allowDownload={false} also hides Download as / Print and blocks Ctrl+P.
<DocViewer
src={file}
fileMenuItems={[{ label: 'Share…', icon: 'open', onClick: share }, { label: 'Version history', onClick: history }]}
onRename={(name) => api.rename(id, name)}
onClose={() => router.back()}
/>CSS is auto-injected, no import needed (or import @p10node/office-engine/styles.css with injectStyles={false}). Container must have a height. Colors, type and shape: Theming.
| Prop | Type | Default | Notes |
|---|---|---|---|
src |
File | Blob | ArrayBuffer | string | URL |
– | Office (also 97-2003); OpenDocument; RTF; Pages / Keynote / Numbers; Visio; CSV / TSV, text, Markdown, HTML, diagrams |
name |
string |
auto | Display name; its extension also tells the format of a Blob / ArrayBuffer |
toolbar |
boolean |
true |
Top bar (name, status, progress) |
toolbarExtra |
ReactNode |
– | Extra buttons on the right of the toolbar |
zoom |
number | 'fit' |
'fit' |
Initial zoom (docx/pptx) |
thumbnails |
boolean |
true |
Thumbnail column for pptx |
headers |
Record<string,string> |
– | Headers for URL requests |
credentials |
RequestCredentials |
– | Cross-origin cookies |
worker |
() => Worker | false |
inline | Custom worker (CSP), false = main thread |
styleTarget |
Document | ShadowRoot |
document | Where CSS is injected |
injectStyles |
boolean |
true |
Inject the stylesheet; false when the page loads @p10node/office-engine/styles.css itself |
theme |
'light' | 'dark' | 'auto' | ThemeOptions |
'light' |
Color scheme of the chrome; 'auto' follows prefers-color-scheme; an object adds token overrides (Theming). Documents keep their own colors |
editable |
boolean |
false |
Open in edit mode (Pages, Keynote, Numbers and Visio files stay view only) |
allowEdit |
boolean |
true |
Show Edit/View button |
allowSave |
boolean |
true |
Show Save/Download button, enable Ctrl+S |
allowDownload |
boolean |
true |
Allow downloads to device (save without onSave, images) |
fileMenu |
boolean |
true |
File menu: open, download as PDF / HTML / text, print |
allowOpen |
boolean |
true |
File → New / Open (off during collaboration) |
captureSelectAll |
boolean |
true |
Ctrl/⌘+A from anywhere on the page selects the document; false: from the viewer only |
fileMenuItems |
FileMenuItem[] |
– | Extra File menu entries (label, onClick, icon, hint) |
icons |
Icons |
built-in | Your own icons: a map by IconName or a resolver (name, { size }) => node; see Icons |
onRename |
(name) => void |
– | File → Rename result (extension included) |
onClose |
() => void |
– | Adds File → Close |
onSave |
(blob, name) => void |
download | Receives saved file (downloads by default): the Office file, or a Markdown / HTML / SVG file as itself |
onDirtyChange |
(dirty) => void |
– | Whether there are unsaved changes |
collab |
CollabOptions |
– | Real-time collaboration, see collaboration |
comments |
CommentOptions | false |
{} |
Comments (see below); false hides them |
onLoad |
(client) => void |
– | |
onError |
(error) => void |
– |
<DocViewer
src={file}
editable
comments={{
user: { id: me.id, name: me.name }, // author of the comments written here
mentions: (q) => api.members(nodeId, q), // or a list: [{ id, name }, …]
onEvent: (e) => e.mentioned.length && api.notify(e.mentioned, e), // notify people mentioned
open: true, // panel open on load
}}
/>CommentOptions |
Type | Default |
|---|---|---|
user |
{ name, id?, initials? } |
the collab user, else "Me" |
mentions |
CommentUser[] | (query) => CommentUser[] | Promise<…> |
none (no @ suggestions) |
canComment |
boolean |
while editing |
onEvent |
(e: CommentEvent) => void |
– |
open |
boolean |
false |
focus |
string (a comment id) |
– |
focus shows a thread when the document opens (a link from a notification): the panel opens on it and the document scrolls to its place.
onEvent is called for the changes made in this viewer (not for collaborators' — each of them reports their own):
CommentEvent |
Meaning |
|---|---|
type |
'add', 'reply', 'edit', 'delete', 'resolve', 'reopen' |
comment |
the comment (DocComment: id, parent?, author, time, text, mentions?, done?) |
thread |
the thread's first comment |
mentioned |
people mentioned by this change: all of a new comment's, those an edit added |
participants |
the people who wrote the thread's other comments (not the one who made the change) |
quote |
what the thread points at: the commented text, Sheet1!B3, Slide 2 |
A comment's author and mentions carry the id the host gave (stored in the file's people / persons / authors list), so a host can tell its users apart after the file was saved and reopened. Ownership (edit / delete) is by user.id when there is one, else by name.
Use individual views / build your own UI:
import { useDocument, DocxView, XlsxView, PptxView } from '@p10node/office-engine'
const { client, error, progress } = useDocument(src)
if (client?.kind === 'xlsx') return <div className="de-root"><XlsxView client={client} /></div>The views style themselves from design tokens on their root: useThemeRoot(theme) gives its class name and style (see Theming).
Every icon the viewer draws, toolbars, menus, zoom, outline, Present and the add-sheet tab included, has a name (IconName, all of them in ICON_NAMES). icons replaces any of them, either as a map or as a resolver that is called for every icon:
import { DocViewer, type IconName, type Icons } from '@p10node/office-engine'
// Define outside the host component so the map keeps its identity across renders.
const icons: Icons = { undo: <MyUndo />, redo: <MyRedo /> }
<DocViewer src={file} icons={icons} />A name the map leaves out, or a resolver returning undefined / null, keeps the built-in icon, so a set can cover just part of the names. Your icon is rendered inside <span class="de-icon"> whose font-size is the icon's size in pixels: draw it at 1em (a bare <svg> child is sized to 1em for you) and with currentColor, so it follows the theme. The resolver also gets { size } in pixels.
The names exported in ICON_NAMES are stable public keys, including names originally used only inside the viewer.
New names may be added; existing keys must not be renamed as an internal refactor.
With Lucide (lucide-react):
import { Bold, Italic, ListTree, Plus, Presentation, Redo2, Replace, Search, Undo2, X, ZoomIn, ZoomOut, type LucideIcon } from 'lucide-react'
const LUCIDE: Partial<Record<IconName, LucideIcon>> = {
undo: Undo2, redo: Redo2, bold: Bold, italic: Italic, search: Search, replace: Replace,
zoomIn: ZoomIn, zoomOut: ZoomOut, outline: ListTree, close: X, present: Presentation, sheetAdd: Plus,
}
const lucide = (name: IconName) => {
const C = LUCIDE[name]
return C && <C size="1em" strokeWidth={1.8} />
}
<DocViewer src={file} icons={lucide} />With Phosphor (@phosphor-icons/react):
import { ArrowArcLeft, ArrowArcRight, ArrowsLeftRight, ListBullets, MagnifyingGlass, MagnifyingGlassMinus, MagnifyingGlassPlus, Plus, PresentationChart, TextB, TextItalic, X, type Icon } from '@phosphor-icons/react'
const PHOSPHOR: Partial<Record<IconName, Icon>> = {
undo: ArrowArcLeft, redo: ArrowArcRight, bold: TextB, italic: TextItalic, search: MagnifyingGlass, replace: ArrowsLeftRight,
zoomIn: MagnifyingGlassPlus, zoomOut: MagnifyingGlassMinus, outline: ListBullets, close: X, present: PresentationChart, sheetAdd: Plus,
}
const phosphor = (name: IconName) => {
const C = PHOSPHOR[name]
return C && <C size="1em" />
}The standalone views get the same icons from IconsProvider, which DocViewer uses internally; a nested provider falls back to the enclosing one for names it leaves out:
import { IconsProvider, XlsxView } from '@p10node/office-engine'
<IconsProvider icons={lucide}>
<div className="de-root"><XlsxView client={client} /></div>
</IconsProvider><script src="office-engine.embed.js"></script> <!-- dist/, bundles React + worker -->
<office-viewer src="/files/report.docx" style="height:600px"></office-viewer>
<div id="v" style="height:600px"></div>
<script>
const viewer = OfficeEngine.mount(document.getElementById('v'), { src: '/files/deck.pptx' })
input.onchange = (e) => viewer.update({ src: e.target.files[0] })
// viewer.destroy()
</script><office-viewer>: attributes src, name, editable, toolbar="false", thumbnails="false", save="false", download="false", file-menu="false", open="false", capture-select-all="false", theme="dark" (or "auto"), collab / room / user / base (real-time collaboration; user also writes the comments), comments="false"; properties .file = File and .icons (map or resolver, as icons above); events load, error, comment (detail: a CommentEvent).
import { DocumentClient } from '@p10node/office-engine/core'
const doc = await DocumentClient.open(fileOrUrl, { onProgress: console.log })
doc.kind // 'docx' | 'xlsx' | 'pptx'
doc.info.from // 'pages' / 'keynote' / 'numbers' / 'visio': an Apple or Visio file, converted to docx / pptx / xlsx / pptx (view only)
doc.info.imported // 'csv' / 'tsv' / 'text' / 'markdown' / 'html' / 'svg' / 'mermaid' / 'plantuml' / 'graphviz': a plain file, built as xlsx / docx (editable)
doc.info.converted // 'doc' / 'xls' / 'ppt' / 'rtf' / 'odt' / 'ods' / 'odp': converted to docx / xlsx / pptx (editable, saved as such)
doc.info.ext // 'xlsm' / 'xltx' / 'docm' / 'dotx' / 'pptm' / 'potx' / 'ppsx' …: the file is that variant, and is saved as it (undefined: plain docx / xlsx / pptx)
doc.on('docx:blocks', (blocks) => {}) // docx: streamed blocks
await doc.call('docx.start')
doc.call('xlsx.load', 0) // xlsx: stream sheet
doc.on('xlsx:progress', (p) => {})
await doc.call('xlsx.block', 0, 1000, 1100) // formatted cells, rows [1000, 1100)
await doc.call('pptx.slide', 12) // slide model with layout/master/theme resolved
await doc.call('xlsx.set', 0, [{ r: 4, c: 1, input: '=SUM(A1:A4)' }])
const clip = await doc.call('xlsx.copy', 0, { r0: 0, c0: 0, r1: 9, c1: 2 }) // cells as they are (values, formats, formulas) + `text` for the clipboard
await doc.call('xlsx.sheetOp', 0, { op: 'paste', range: { r0: 20, c0: 0, r1: 29, c1: 2 }, cells: clip.cells, from: { sheet: clip.sheet, r0: 0, c0: 0 } })
await doc.call('xlsx.sheetOp', 0, { op: 'clear', range: { r0: 0, c0: 3, r1: 1048575, c1: 3 } }) // a whole column, every row of it
await doc.call('xlsx.import', 0, csvFile, { name: 'cities' }) // a new sheet after sheet 0 with the rows of a CSV / TSV, streamed in when loaded
await doc.call('xlsx.text', 0, ',') // the sheet as CSV (a Blob; '\t' for TSV), the values as shown
// open(src, { residentCells: 12_000_000 }): cells of a CSV / TSV kept in memory; the other rows are read from the file as they are shown
// open(src, { encoding: 'windows-1258' }): the encoding of a text file (CSV, TSV, text, Markdown, HTML…), a TextDecoder label; without it the
// byte order mark, the declared charset, UTF-8, then (Vietnamese text) Windows-1258, then Windows-1252 decide. An unknown label is an error
// the worker also emits `warning` ({ text }) when a file opened but not whole: a CSV with more than 16,384 columns (the viewer shows it as a message)
const comments = await doc.call('comments.list') // DocComment[]: threads are roots + replies (threadsOf)
doc.on('comment', ({ id, c }) => {}) // a comment set / deleted (c null), here or by a collaborator
await doc.call('comments.set', c.id, { ...c, done: true }) // XLSX / PPTX threads carry their place (`at`)
const blob = await doc.call('save') // edited file
await doc.call('plain.source') // text of a Markdown / HTML / diagram file (null for other files)
doc.destroy()Diagrams and Markdown without the viewer (no DOM needed, no dependency): @p10node/diagram, @p10node/mermaid, @p10node/plantuml, @p10node/graphviz, @p10node/markdown.
import { render, renderPage } from '@p10node/diagram'
const { svg, width, height } = render('sequenceDiagram\n Ann->>Ben: hi') // language detected
renderPage() // <pre class="mermaid">, <code class="language-dot">… of the page become drawings
import { render as markdown } from '@p10node/markdown'
el.innerHTML = markdown(text) // safe HTML; ```mermaid / ```plantuml / ```dot drawnThe default worker is an inline blob → requires worker-src blob:. If that's not allowed, host dist/office-engine.worker.js (exported as @p10node/office-engine/worker) on the same origin:
<DocViewer src={src} worker={() => new Worker('/static/office-engine.worker.js', { type: 'module' })} />Links from a document (DOCX text and pictures, PPTX text) are clickable in view mode when they point to http(s), mailto, tel, sms, ftp(s), a relative path or a place in the document (#bookmark). Other targets (javascript:, data:, vbscript:, file:…) show as plain text, also in the web page and Markdown exports, so a crafted file cannot run script in the host page. The file itself keeps its links unchanged. External links open in a new tab with rel="noreferrer noopener".