Headers and footers

The editor renders headers and footers at their authored positions and edits them in place. Users double-click the header or footer area to open it. Undo, redo, and save cover these edits.

Edit a header or footer from code

The automation API returns each header or footer variant as a Body proxy:

await runtime.run(async (context) => {
  const section = context.document.sections.getFirst();
  await context.sync();
  const footer = section.getFooter('Primary');
  footer.load('text');
  await context.sync();
  footer.insertText('Internal document', 'End');
  await context.sync();
});

getHeader(type) and getFooter(type) accept Primary, FirstPage, or EvenPages. For story rules, see Page layout and stories.

Insert page fields

Run insertPageField while a header or footer is open:

const result = editor.exec({ type: 'insertPageField', field: 'PAGE' });
if (!result.ok) console.warn(result.reason);

Outside a header or footer scope, the command returns ok: false with code unsupported.

Page fields stay DOCX fields and update when the document reflows. The header Options menu offers the same insertions. For switch support, see Fields and cross-references.

Set a watermark

Run setWatermark to add or change a watermark. This example adds a diagonal text watermark:

const result = editor.exec({
  type: 'setWatermark',
  watermark: { text: 'CONFIDENTIAL', layout: 'diagonal', transparency: 0.5 },
});
if (!result.ok) console.warn(result.reason);

Each call is one undo step. A refused call writes nothing and returns a reason that names the option, for example color must be RRGGBB. Pass watermark: null to remove the watermark.

A watermark stacks with the other pictures behind the header text in the order the document sets.

Set either text or imageData, never both. This example sets a picture watermark from a user file:

async function setPictureWatermark(file: File) {
  const imageData = new Uint8Array(await file.arrayBuffer());
  return editor.exec({ type: 'setWatermark', watermark: { imageData, washout: true } });
}

Read the watermark

Customize header controls

Replace the Watermark popup through popups.watermark. This example changes the text presets:

import { DocxEditor } from '@docx-editor.dev/react';

<DocxEditor
  popups={{
    watermark: (props) => (
      <DocxEditor.WatermarkDialog {...props} presets={['INTERNAL', 'CONFIDENTIAL', 'DRAFT']} />
    ),
  }}
/>;

Pass preset={false} to compose the parts yourself. DocxEditor.WatermarkDialog.Preview draws the caret's section page. For a custom preview, watermarkShapeBox returns the shape size in points:

import { watermarkShapeBox } from '@docx-editor.dev/core/editor';

// A Letter page with one-inch margins has a 468 by 648 point text area.
const box = watermarkShapeBox({ text: 'DRAFT' }, { width: 468, height: 648 });

The shape is centered on the text area. A diagonal shape turns 45 degrees counterclockwise. For popup composition, see Customize popups.

Limits

• Editing a shared header or footer changes every page that uses that part.
• w:titlePg selects the first variant. w:evenAndOddHeaders alternates default and even variants.
• Sections without their own references inherit them from earlier sections.
• A page with no reference for its selected variant shows no header or footer.
• Blank pages added by odd-page or even-page section breaks have no header or footer.
• The automation API does not expose header and footer linkage or first-page layout toggles.
• One watermark applies document-wide. The command creates a default header when a section has none.
• Forms protection refuses setWatermark with locked.
• Text boxes in headers open on double-click. See Edit text boxes.
• Legacy frames, continuous sections, and page-number switches follow DOCX fidelity.

See also

• Page layout and stories
• Fields and cross-references
• Advanced drawing rendering