@reductoai/docx-editor API:
This guide shows the pattern that both demos follow. The examples use Svelte 5, but each step is plain calls on
EditorModel, so the same steps work in React, Vue or vanilla JS.
Choose how much to replace
If you only need to remove or add a few buttons, you do not need a skin: use
toolbarItems on the built-in format bar.
Start with slots. Both demos do. The review margin, the ruler and the dialogs are a large amount of work, and a slot lets you keep them while you replace the parts that the user sees first.
1. Mount the editor with your slots
A slot is a function that gets a host element and the model, and returns a cleanup. The host element isdisplay: contents, so your markup sits in the editor’s grid where the built-in region was.
null to remove the region, or pass a function to put your markup there.
Find lives in the
nav region: model.find.show() and Ctrl+F open the pane on its results tab. If you set nav to null, render your own find box while model.find.open is true, or find has no UI.
A region that is outside the editor (a title bar, a menu bar, a ribbon) is not a slot. Put it next to the mount element and give it editor.model.
In React, each slot is a prop that takes a node: <DocxEditor toolbar={<MyToolbar model={model} />} selection={null} />.
2. Bind your UI to the model
EditorModel is an Observable. subscribe(fn) calls fn on every change. subscribe(fn, "format") calls it when one field changes. Side models (review, find, nav, spell, ui) are adopted children, so a change in them also reaches a listener on the model.
Both demos use one small bridge, so that a template runs again when the model changes:
useObservable(model, (m) => ({ bold: !!m?.format?.bold })). Always give a selector to a component that stays mounted, because the model changes on each caret move.
Fields that a skin reads most:
3. Run commands
There are three ways to run a command. Use the highest one that does the job:- A keymap command:
model.keys.run("format.bold"). The keymap also gives the shortcut text (keys.label(id)), a tooltip (keys.title(id, "Bold")) and the enabled state (keys.enabled(id)). Your button, menu item and shortcut then always agree. See Keyboard shortcuts for the ids. - A method:
toggleBold(),setAlignment("center"),toggleList("bullet"),applyRunFormat({ font: "Arial" }),undo(),startComment(),pickImage(),copyFormat()andpasteFormat(). - An
EditorCommand:await model.run({ kind: "paragraphFormat", format: { styleId: "Heading1" } }). Every edit is one of these. ReadEditorCommandfor the full list.
runClipboard(model, "paste", "text"), openLinkDialog(model), selectTablePart(model, "row"), bookmarks, notes, headers and footers, and insertTextFromFile.
Keep the caret
A click on a toolbar button must not take focus from the document. If it does, the selection goes away before the command runs.- Call
event.preventDefault()onmousedownin the toolbar. Do not do this on text inputs (the font size box). - After a popup or dialog closes, call
model.focusInput().
4. Build menus from data
Both demos keep menus as data: a list of entries that a function builds when the menu opens. The function reads the model at that time, so checked and disabled states are always current.model.version first, so that the menu updates while it is open: {@const entries = (m.version, popup.build())}.
If your menu has an entry that you cannot serve yet, give it a reason (missing above). Show the entry greyed out, with the reason as its tooltip. The user then knows the feature is planned, not lost.
Put your menus in the command palette
The built-in palette (model.ui.palette) searches registered providers. Register one that walks your menus, and “search the menus” finds every leaf:
5. Fill galleries and lists
Fonts, colours and galleries has the data that a font box or a Word gallery needs:
Each gallery value is the payload of one
EditorCommand, so a click is one model.run(...).
6. Context menu
The editor decides what a right click offers. It puts the rows inmodel.ui.contextMenu (open, x, y, items). Your contextMenu slot only draws them:
model.ui.contextMenu.close() and then model.focusInput().
7. Floating UI over the pages
To place a bubble next to the selection, usemodel.selectionBox() (client coordinates) and model.layerFor(pageIndex) (the page element). Hide the bubble while model.pointing is true (a drag is in progress) or while model.ui.contextMenu.open is true. Listen for scroll (capture) and resize and place it again.
8. Panels: navigation, find, review, spelling
Read Review, find and navigation models for each member.
9. Your own commands and keys
Register host actions (open, print, a dialog) as keymap commands. Then a shortcut, a menu item and the palette all run the same thing, and the user can change the key:register returns a function that removes the command. Call it when the skin unmounts, before editor.destroy().
10. Files
Show errors with
model.fail(message). The editor shows them in its own toast.
11. Dialogs
You can keep the built-in dialogs and call them from your chrome, for examplemodel.ui.openAuthorDialog(model.revisionAuthor). To draw a dialog of your own, read the current values from model.format (for page setup, format.section), then send one command when the user clicks OK:
12. Look and feel
- Override the CSS tokens of the editor (
--rd-accent,--rd-radius,--rd-font-sans, and the others in@reductoai/docx-editor/tokens.css) so that the pages, rulers and built-in panels match your chrome. The tokens are in a cascade layer, so a plain:rootrule wins whether your CSS loads before or after the package’s. - Give your own classes a prefix, so that they do not collide with the editor’s classes.
- The editor’s reset and base font apply only under the
reductoaiclass. Your chrome outside the mount root keeps your page’s styles. To give it the editor’s base, addclass="reductoai"to its root. - Your slot markup is in the editor’s grid. Style it as a grid item.
Checklist
- Disable controls when
model.irisnull. - Prevent focus loss on
mousedown, and callmodel.focusInput()after each popup. - Prefer
model.keys.run(id)for commands that have a shortcut. - Build menus when they open. Do not cache them.
- Remove every
registerandsubscribewhen the skin unmounts. - Keep
window.editor = modelin development builds. You can then try a command in the console before you add a button for it.