Skip to main content
A skin is your own chrome around the editor’s pages: a toolbar, a menu bar, panels and dialogs that look like your product. Two demos are skins of this type. They use only the public @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 is display: contents, so your markup sits in the editor’s grid where the built-in region was.
For each slot: leave it out to keep the built-in, pass 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:
In React, use 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:
  1. 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.
  2. A method: toggleBold(), setAlignment("center"), toggleList("bullet"), applyRunFormat({ font: "Arial" }), undo(), startComment(), pickImage(), copyFormat() and pasteFormat().
  3. An EditorCommand: await model.run({ kind: "paragraphFormat", format: { styleId: "Heading1" } }). Every edit is one of these. Read EditorCommand for the full list.
Some actions need more than one command, or a browser API. Editor actions has them as functions: 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() on mousedown in 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.
To show a menu, call the builder inside the template and read 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 in model.ui.contextMenu (open, x, y, items). Your contextMenu slot only draws them:
When the user picks a row or clicks outside, call model.ui.contextMenu.close() and then model.focusInput().

7. Floating UI over the pages

To place a bubble next to the selection, use model.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:
Each 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 example model.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 :root rule 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 reductoai class. Your chrome outside the mount root keeps your page’s styles. To give it the editor’s base, add class="reductoai" to its root.
  • Your slot markup is in the editor’s grid. Style it as a grid item.

Checklist

  • Disable controls when model.ir is null.
  • Prevent focus loss on mousedown, and call model.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 register and subscribe when the skin unmounts.
  • Keep window.editor = model in development builds. You can then try a command in the console before you add a button for it.