Skip to main content
Custom components are an alpha feature. The API can change in a future release.
A custom component is your own UI inside a document: a signature box, a sortable table, an approval stamp. The editor shows your live view. The file keeps plain Word content, so Word and the PDF show it too. A component has two parts:
  • Fallback. Word content made from the component’s state: a picture, a table, or free content. Word, the layout and the PDF show it.
  • Live view (optional). DOM mounted over the fallback’s box. It edits the document only through commit(state).
The fallback keeps the component’s type, id and JSON state: Word keeps this data through edits, moves, resizes, copies and sorts. If the user deletes the content, the component is gone. If the data is lost, the content stays as a plain picture, table or text.

Define a component

  • type: the component kind. Letters, digits, ., _ and -, with your own prefix.
  • fallback(state): returns the Word content. Keep it pure. It runs on each state change, not at save.
  • read(rows, stored): table components only. Turns the cells back into state, because a Word user can edit them.
Fallback kinds:
  • picture: PNG, JPEG, GIF, BMP, TIFF, EMF or WMF bytes, with an optional svg for sharp output. See A QR code.
  • table: rows of strings (the first row is the header) and an optional style.
  • content: ooxml. See Free content.

Add a live view in the editor

Pass components to mountDocxEditor as components. mount(el, ctx) gets a node over the fallback’s box. The node moves and scales with the page, so size your view in % or cqw/cqh. The node ignores the pointer: set pointer-events: auto on the parts a user clicks. When a user turns or mirrors a picture, the node turns with it; ctx.rotDeg and ctx.flip give the angle and the mirror. drawPicture(widthPt, heightPt, draw) makes a PNG fallback from a canvas. insertComponent(model, def, state) inserts a component at the caret. Scroll to the end of the lease. Draw a signature in a yellow box, then click Adopt and Sign. The strokes go into the state and the fallback becomes a DocuSign-style stamp. Undo restores the empty box in one step. Word shows the same stamp. WordDocument writes the lease with Office.js, and the headless insertComponent puts a signature box in each table cell. The pad keeps the strokes until Adopt and Sign, so signing is one edit, not one per stroke.

Check the round trip

Each live editor has .docx, PDF and Open buttons. To check that the file keeps the component:
  1. Sign, then click .docx.
  2. Open the file in Word, edit the text around the fallback, and save.
  3. Click Open and select the saved file. The live view comes back with its state.
The PDF shows what a reader without the editor sees.

A sortable table

A table component keeps its data in the cells. A Word user can edit cells, add rows or sort, and read gets the change. The state keeps only view settings, here the sort column. The view adds a row of sort buttons above the table. The canvas still paints the real table, so it can split over pages. A split table gets one view per page; ctx.part and ctx.parts tell them apart. Edit a cell, then sort: the sort uses your edit. A sort is a real edit, so Undo reverts it. Rules:
  • The table is the data. Read the cells with read. Do not copy them into the state.
  • The view must fit the table’s box. It cannot change pagination. Put controls on or next to the table, not a second table over it.

A picture that plays

The view can show what Word cannot. Here the file keeps a pixelated first frame of a GIF, and the editor plays the GIF on click. fallback can be async. The view takes no pointer events. It listens on the window and treats a press and release with no move as a click. A click plays the GIF; a drag moves the picture like any float. The click changes no state, so it is not an edit. Word and the PDF show the pixelated frame.

A QR code

A picture fallback can carry an SVG next to its PNG. Word shows the SVG, which stays sharp at any size and in print. A reader that cannot show an SVG uses the PNG. Here uqr makes the QR code, and the view is a bubble that shows when you point at the code. On this page, other packages load from esm.sh. In your app, run npm install uqr. Point at the code, type a link in the bubble and press Enter: the code is drawn again as one undo step. The bubble is editor UI. It is not in the file, so Word and the PDF show only the code.

A chart from a library

A view can use any drawing library. Here Chart.js draws the chart twice: still, as the fallback, and live, as the view, with tooltips and a chart type toggle. In your app, run npm install chart.js. Word and the PDF show the still chart. A type change draws the fallback again as one undo step. Draw the fallback with animation: false, so it shows the final chart, not the first frame.

Free content

A content fallback is any Word content: paragraphs, lists, tables and pictures, with styles. contentFallback(build) gives build the body of a blank document to write with the usual API. Or pass { kind: "content", ooxml } with a Flat OPC package or a body fragment. The content fills whole paragraphs. insertComponent puts it after the caret’s paragraph. In the file it is the result of an ADDIN field whose code keeps the type, id and state. Word never updates an ADDIN result, so F9 and printing do not change it. Click + Add a seat: the content is written again from the new state, as one undo step. At 15 and 25 seats a green discount row appears, and a total over $8,000 turns red with a note for Finance. This is plain Word formatting, so Word and the PDF match. The view covers the content on each page; content that spans pages gets one view per page. Rules:
  • The state is the data. The next commit writes the content again from the state and drops edits inside it. Text typed outside the field, in its first or last paragraph, stays.
  • Unlinking the field (Ctrl+Shift+F9) keeps the content as plain text and removes the component.
  • Alt+F9 shows the field code and the state. Do not put secrets in the state.

Work with components

mountDocxEditor returns components for use from your own toolbar: A copied component keeps the same id. list() gives the copy its own key (id-copy2), which becomes its id on the first commit. To remove a component, delete its content as a user would. ctx.select() puts the caret on it.

Without the editor

@reductoai/docx/components works on a WordDocument in Node or the browser, for example to fill in components on a server or read them back after signing. This example uses the stamp component from Define a component:
insertComponent adds the component in a new paragraph at the end of the body, or at the end of the paragraph you give it. In Node, fallback runs with no DOM: drawPicture needs a canvas, so it works only in the browser. componentBoxes(layout, component) returns a component’s boxes on the laid-out pages, for your own overlays or a PDF signature field.

Use cases

Limits

  • A .docx is not proof. Anyone with the file can change it, state included. For a legal signature, keep the audit data on your server and treat the signed PDF or a file hash as the record.
  • Validate state you read back. Treat state as user input: Word users can edit alt text and tables.
  • A float placed on the page does not move with the text and can end up over it. Put a component inline when it belongs to a paragraph.
  • Picture tools change the fallback, not the state. To keep a fixed size, draw the fallback again on the next commit.
  • Only body components are read. In headers, footers and notes they stay as their fallback.