API reference

Public methods and properties of the UniversalWriteElement class (the <universal-write> element), grouped by area.

Built-in chrome (toolbar & status bar)

The component can render its own top toolbar and bottom status bar — no external chrome to wire. They are set via attributes (or the matching properties) and load Material on demand, so the default costs nothing.

<universal-write topbar bottombar></universal-write>
<universal-write topbar toolbar="ribbon" bottombar></universal-write>

// or at runtime, via properties
editor.topbar = true;     // boolean
editor.bottombar = true;  // boolean
editor.setAttribute('toolbar', 'ribbon');

// optional: what only the host app can do (e.g. an Electron shell)
editor.host = {
  openFile: () => bridge.open(),                 // { name, bytes, motw? } | null
  saveFile: (bytes, { name, format, saveAs }) => bridge.save(bytes, name),
  setDirty: (dirty, name) => bridge.setDirty(dirty, name),
  windowControlsOverlay: true,                   // frameless window
};

Commands whose editor API does not exist yet stay hidden, so new editor features appear in the bars as soon as their method exists.

Light and dark

The element follows the CSS color-scheme of its context (inherited from the page, across the shadow DOM): every color of the bars, menus, dialogs, popovers, rulers, panes, status bar and desk is a --u-color-* token or a light-dark() color, so switching is pure CSS and live. It never looks for u-dark/u-light classes — only at the resulting color-scheme. Without theme/accent, the bars use the page’s --u-color-* tokens when it defines them, otherwise the accent palette. The page stays white in dark mode (like Word and Google Docs); theme="black" or setDarkPage(true) darkens it too.

Side panel (slot="side")

Light DOM children with slot="side" (or slot="side-start") show below the bars (title, menus, notice, toolbar, ruler) and beside the pages, like Google Docs’ comments pane: the toolbar keeps the full width and the pages shrink and re-center. The host owns the panel — its own component in the light DOM, so the page’s styles apply — and sets its width and visibility; an empty or hidden slot takes no space. The panel sticks below the bars, as tall as the space between them, and scrolls by itself; with pages wider than the space left (high zoom) it stays at the visible edge over them.

Clicks, keys, the wheel and dropped files in the panel are the host’s: the editor does not take the focus, move the caret, open its context menu, zoom or turn pages there, and fires no uw-file-drop; only the app shortcuts (open, save, print, find) still work, as from a field of the bar. Events still bubble to the page. The panel is left out of printing and inherits the element’s color-scheme.

<universal-write topbar>
  <app-document-data slot="side" style="width: 320px"></app-document-data>
</universal-write>

Notice band

setNotice(el, { tone }) shows a band of the host’s own between the title/menu row and the tools — in the compact bar before the toolbar row, in the ribbon before the tabs — like Google Docs’ and Drive’s storage warnings (someone else is editing, read-only, storage almost full). The element moves into the bar, so it inherits the bar’s theme (light/dark, accent, one background color, font) and the bar kit’s buttons fit in it. It stays in read mode, survives switching toolbar and the UI language, is announced by screen readers (role="status") and only shows with topbar.

const ui = await loadBarKit('pt');
const band = document.createElement('div');
band.style.cssText = 'display:flex;align-items:center;gap:12px;flex:1';
band.append(
  ui.createBarIcon('warning', { size: 18 }),
  Object.assign(document.createElement('span'), { textContent: 'Maria Souza está editando este documento.', style: 'flex:1' }),
  ui.createBarButton({ label: 'Tentar de novo', variant: 'text', size: 'small', onClick: retry }),
);
editor.setNotice(band, { tone: 'warning' });
editor.setNotice(null); // remove

Formatting policy

For documents whose look comes from a template (styles, fonts, spacing, borders and page setup are the template's job), the host gives the editor a formatting policy, like Quill's formats whitelist. What the policy leaves out disappears from the bars, menus, context menu, galleries, dialogs and shortcuts (the hidden-commands mechanism), the editing API ignores it and paste converts or drops it. Content already in the document is never touched: loading and saving do not filter.

import { TEMPLATE_DOCUMENT_POLICY } from '@universal-office/write';

editor.formattingPolicy = TEMPLATE_DOCUMENT_POLICY;   // or <universal-write formatting-policy="template-document">
editor.formattingPolicy = { ...TEMPLATE_DOCUMENT_POLICY, tables: false };
editor.formattingPolicy = null;                       // no policy

TEMPLATE_DOCUMENT_POLICY (formatting-policy="template-document") behaves like a lightweight rich-text editor (such as Quill) for documents whose look comes from a template: styles Normal, Heading 1–3, Title and Subtitle; bulleted and numbered lists in 9 levels; bold, italic, underline, strikethrough, font color, highlight and links; alignment and Increase/Decrease Indent; pictures, tables, columns and page breaks. Everything else (fonts, sizes, superscript, spacing, borders, shading, page setup, headers and footers, shapes, style editing, Format Painter) belongs to the template.

Paste follows the policy for every source (the editor's own copy, HTML from browsers and Word, plain text): a style that is not allowed becomes the nearest allowed one (Heading 5–9 → the deepest allowed heading; Title → Heading 1 when Title is not allowed; anything else → Normal); character and paragraph formats outside the policy are dropped; lists of any format (including Word's mso-list paragraphs) become bulleted or numbered lists within the allowed levels; tables stay tables or, with tables: false, their cells become paragraphs; pictures and shapes that are not allowed are dropped; unknown tags keep their text, as in Word. Plugin inlines copied inside the editor paste as inlines; from anywhere else, as their fallback text.

Dropped files

Every file dropped on the element first fires the cancelable uw-file-drop (detail: { files, clientX, clientY }), before the editor handles it; preventDefault() hands the files to the host. Not canceled, dropped pictures are inserted at the drop point (editable document, policy with images) and, with topbar, a dropped .docx/.odt/.doc opens. With nofiledrop the editor never opens or inserts dropped files; the event still fires and the browser never navigates to them.

editor.addEventListener('uw-file-drop', async (e) => {
  const file = e.detail.files[0];
  if (!/\.docx$/i.test(file.name)) return;   // let the editor handle it
  e.preventDefault();
  if (await confirmReplace(file.name)) editor.load(new Uint8Array(await file.arrayBuffer()));
});

Document (load, save, export)

Document state

View and zoom

Text formatting (runs)

Paragraph formatting

Styles

The document’s styles.xml is edited in place: each operation rewrites only the w:style elements it touches and leaves the rest byte for byte. New and modified styles are written the way Word writes them (a new paragraph style is linked, with a …Char twin; its id is the name without accents or spaces; a built-in style used for the first time gets Word’s full definition). Built-in names follow the UI language (heading 1 → “Heading 1” / “Título 1”). With topbar, the ribbon’s Styles group is a thumbnail gallery, its launcher opens the Styles pane, and Format › Styles (compact bar) has the pane, the Style Inspector and the Create/Modify Style dialog.

Enter at the end of a paragraph whose style has a next style (Heading 1 → Normal) starts the new paragraph in that style, without direct formatting.

Inserting content

Tables

Tables follow Word’s rules (measured against Word): what each operation does to widths, merges, borders and styles, and what it writes to the file. Every operation is one undo step, works in nested and floating tables and is refused in Protected View. A table read from the file keeps its original XML for everything the operation did not touch (rows, cells, content controls and bookmarks inside it). With topbar: Insert › Table, Format › Table, Tools › Sort (compact bar), the contextual Table Design and Table Layout tabs (ribbon) and the context menu.

Pictures

Pictures follow Word’s rules (measured against Word): the XML each operation writes, the wrap and position it keeps, how effects and adjustments are drawn on the page and in the PDF. Every operation is one undo step and edits only the picture’s own XML. With the mouse: round handles resize (corners keep the aspect ratio when it is locked, Shift inverts, Ctrl from the center), the handle above rotates (Shift: 15° steps), dragging moves (an inline picture moves in the text), arrows nudge a floating picture, Delete removes it. With topbar: the contextual Picture Format tab (Adjust · Picture Styles · Accessibility · Arrange · Size), the compact bar’s Picture group, Format › Picture, the context menu, the Format Picture, Alt Text and Selection panes and the Layout and Compress Pictures dialogs.

Shadows, reflection, glow, soft edges and bevels are drawn with models measured against Word, on the canvas and in the PDF (each effect as an RGBA image with a soft mask, like Word). Not included: Remove Background, Artistic Effects (kept when present in the file), Picture Layout, online pictures and icons; 3-D rotation is kept and saved but drawn flat.

Shapes and text boxes

Text boxes and shapes follow Word’s rules (measured against Word): the XML each operation writes (wps:wsp inside mc:AlternateContent with the VML fallback rebuilt like Word), linked text boxes and the text flowing between them, vertical text and the theme’s shape styles. Click inside a text box to edit its text (one undo stack with the document, like Word); click its border to select the shape: round handles resize, the handle above rotates, dragging moves; Esc in the text selects the shape, typing with the shape selected adds to its text, Delete removes it, Ctrl+C / Ctrl+V copy it. A document in compatibility mode (Word 2007 or earlier) and a text box that came only as VML stay VML when saved, like Word. With topbar: the contextual Shape Format tab (Insert Shapes · Shape Styles · Text · Accessibility · Arrange · Size), Insert › Text Box (gallery and Draw Text Box), the compact bar’s Shape group, Format › Shape, the context menu and the Format Shape pane.

Not included: WordArt styles, inserting new shapes, Edit Points and grouping (separate work items), Word’s own Text Box gallery designs and textures; 3-D rotation is kept and saved but drawn flat.

Home tab: font, lists, clipboard, text effects, editing

What the Home tab of the built-in bars does, as public methods. The behavior was measured in Word (Office 365, pt-BR) — the XML each command writes and how the page is drawn.

Font

Lists

Clipboard and paste options

Text effects and typography

Find, replace, go to and selection

Clipboard, find and replace

Navigation Pane, ruler and gridlines

With topbar, View › Show turns on the Navigation Pane (also Ctrl+F), the Ruler and the Gridlines, as in Word. The pane has a search box and three tabs: Headings (the tree of the body's headings — click to go, collapse/expand, drag a heading to move its whole section, right-click to promote/demote, add, delete or select), Pages (thumbnails) and Results (the matches with the text around them). The heading tree is built like Word's (checked on real documents): the built-in Heading styles count by name even without w:outlineLvl, list numbers and All Caps show as in Word, headings in tables and empty ones are left out. The ruler shows the margins, the section's columns, the table cells, the paragraph's indents and tab stops (centimeters with lang="pt" or lang="es", inches otherwise): drag to change them (0.25 cm or 1/16" steps; Alt = free), click to set a tab, drag a tab off to remove it, double-click for Page Setup, Paragraph or Tabs. Dragging writes what Word writes: only the attributes that differ from the style, tab stops in position order and w:val="clear" for a style's tab that was removed. Gridlines draw the document's drawing grid (9 pt from the margins by default) on screen only.

Header and footer

With topbar, editing a header or footer shows the Header & Footer tab of the ribbon (the compact bar has the same under Insert › Headers & footers): galleries of built-in designs for the header, the footer and page numbers (top or bottom of the page, page margin, current position), Date & Time, Document Info, Go to Header/Footer, Previous/Next, Link to Previous, Different First Page, Different Odd & Even Pages, Show Document Text, the distances from the page edge and Insert Alignment Tab. Each page shows the name of its part (“First Page Header -Section 2-”) and “Same as Previous” when it comes from the previous section. What is written follows Word: unlinking copies the inherited part into a new part of the section (pictures included), linking removes the section's part from the file, page numbers from the galleries are kept in the block Remove Page Numbers finds, Update automatically inserts a TIME field. Text, headers/footers and these options share one undo history; saving keeps the header or footer in editing.

Page fields and a cover page

The page fields follow Word (measured in Word 365 with a cover page — Different First Page and numbering starting at 0 — and three more pages): on the page after the cover PAGE is 1, NUMPAGES is 4 (every page, the cover included) and SECTIONPAGES counts the pages of the page's own section (4 with one section, 3 with the cover in a section of its own). The total without the cover is a formula field: Page { PAGE } of { = { NUMPAGES } - 1 } → “Page 1 of 3” (in Word: Ctrl+F9 for the braces, = , Ctrl+F9 again for NUMPAGES, - 1, F9).

The layout engine (screen, PDF, viewer, .NET) recalculates formula fields as Word does when it paginates: in headers and footers always, in the body only when the code has a nested field. The evaluation is small and safe: numbers (pt-BR notation), + - * /, parentheses and sign over PAGE, NUMPAGES, SECTIONPAGES, SECTION and nested formulas; the result as Word shows it (up to two decimals), with \# "00" or \* roman/ROMAN/alphabetic/Arabic. Anything else keeps the cached result. The model keeps the nested code in Run.fieldCode (" = { NUMPAGES } - 1 ") and saving writes the nested fields back.

Cover pages from Word's gallery. When the body has a cover page from Word's gallery (Insert › Cover Page: a content control with w:docPartGallery “Cover Pages”) and the first section starts numbering at 0 (w:pgNumType w:start="0", which Word writes with that cover), Word's NUMPAGES already leaves the cover out (3 in the example above, so { = { NUMPAGES } - 1 } gives 2). The engine does the same, and only then: without the gallery control, with any other start (or start="0" only in a later section), NUMPAGES counts every page, and SECTIONPAGES never leaves the cover out. The editor's own Insert › Cover Page turns on Different First Page but does not start the numbering at 0.

Page design (watermark, page color, cover page)

With topbar, the ribbon's Design tab has the Page Background group (the compact bar: Format › Page background): the Watermark gallery (Confidential, Do Not Copy, Draft, Sample, ASAP, Urgent, diagonal and horizontal, in the UI language) with Custom Watermark (picture with scale and washout; text with language, font, size, color, semitransparent, diagonal or horizontal) and Remove Watermark; Page Color with the theme palette, standard colors, No Color, More Colors and Fill Effects (gradient with one or two colors or our own presets and the six shading styles, texture, the 48 patterns, picture); and Page Borders. Insert › Pages adds Cover Page (our own designs, filled from the document properties or with placeholders) and Blank Page. What is written follows Word: the watermark is VML in the first paragraph of the three headers of the section (Word recognizes and removes it), the page color is w:background (+ v:background for the effects) with w:displayBackgroundShape, the cover page is a w:sdt “Cover Pages” at the start ending in a page break, with Different First Page. The page color and fill show on screen, always go into the PDF and stay out of printing, as in Word.

Text layout (hyphenation, line numbers, indent and spacing)

With topbar, the ribbon's Layout tab has the Line Numbers and Hyphenation menus (Page Setup group) and the Indent / Spacing boxes (Paragraph group: left/right indent in cm with lang="pt"/"es" or inches, spacing before/after in pt with Auto below 0; type any unit, Enter applies, Esc restores); the compact bar has both menus under Tools. Hyphenation: None, Automatic, Manual (word by word, inserting optional hyphens) and Hyphenation Options (hyphenate automatically, words in CAPS, zone, consecutive hyphens limit). Line Numbers: None, Continuous, Restart Each Page, Restart Each Section, Suppress for Current Paragraph and Line Numbering Options (Page Setup › Layout › Line Numbers: start at, from text, count by, numbering). The Paragraph dialog has a Line and Page Breaks tab and Page Setup has Margins, Paper and Layout tabs. Ctrl+- types an optional hyphen and Ctrl+Shift+- a nonbreaking hyphen. Everything is written the way Word writes it; line numbers are drawn on screen, in the PDF and in print with the Line Number style.

Footnotes and endnotes

Notes are edited in place: clicking the note area (bottom of the page, or the endnotes after the text) enters the note; Esc or a click in the text goes back. Text and notes share one undo history. Deleting a reference deletes its note; the first Backspace right after a reference only selects it; pasting a copied reference creates a new note with a copy of the text. With Track Changes on, a new note is an insertion and a deleted reference keeps its note until the deletion is accepted; revisions inside notes appear in getRevisions() (story: 'footnote' | 'endnote') and in Accept/Reject All. Ctrl+Alt+F / Ctrl+Alt+D insert a footnote / endnote.

Links and references

Bookmarks, cross-references, captions, the table of figures, the table of contents and hyperlinks are written the way Word writes them (bookmark XML and ids, hidden _Ref/_Toc bookmarks, complex REF/PAGEREF/NOTEREF fields, SEQ/STYLEREF captions, multi-paragraph TOC fields). Bookmarks follow edits like Word's: typing at the start of a bookmark goes inside it, at the end it stays out; deleting the whole bookmarked text deletes it; cut and paste moves it, copy does not duplicate it. The layout engine computes REF (exact bookmarked text, \n \r \w \d, \p above/below), NOTEREF, STYLEREF (\s, \n) and SEQ \s n the way Word does when it prints or exports. F9 updates the fields in the selection (Ctrl+A, F9: all); Ctrl+click follows a cross-reference inserted as a hyperlink.

Table of contents

Tables of contents are TOC fields written the way Word writes them: entries in the TOC 1–9 styles with a right tab and leader, each one a hyperlink to a hidden _Toc bookmark on its heading with a PAGEREF page number. The gallery tables sit in a content control (w:sdt with docPartGallery="Table of Contents" and docPartUnique) with a TOC Heading paragraph — one per document, so a new one replaces it. With the caret inside, the control shows its frame and a tab with the gallery menu and Update Table… (screen only). The bars ask, like Word, whether to update only the page numbers or the entire table (the Update Table button, the control's tab and F9).

Comments

Track changes

With tracking on, typing, deleting, Enter and formatting become revisions with author and date, written as Word writes them (w:ins, w:del, w:rPrChange, w:pPrChange, paragraph marks). The state is saved in the .docx (w:trackRevisions). PDF export and printing follow the markup mode on screen.

TOC, navigation and page setup

Plugins

Plugin interface details (inline renderers, bar contributions) and a full example in Plugins.