Work with headers and footers

Each section can include headers and footers for default pages, the first page, and even pages. Users can edit headers and footers directly in the editor UI. Inside a transaction, use Section.headersAndFooters() to access them programmatically.

As of 1.17.0, double-clicking the header or footer area switches the editor into header or footer editing. The toolbar’s Header/Footer panel includes controls for toggling first-page and odd/even-page variants and adjusting the distance between the page edge and the header or footer.

Headers and footers work like images and shapes and footnotes and endnotes: They’re existing document containers. The API edits headers and footers that already exist in the document. If a variant doesn’t exist, its accessor returns null. The API doesn’t create new header or footer variants from scratch.

Before you start, make sure the Document Authoring library is installed and running in your app. If you haven’t set it up yet, refer to the getting started guide.

The examples omit error handling. Add it before you use this code in production.

Edit headers and footers in the UI

Double-click the header or footer area on any page to start editing it. The toolbar’s Header/Footer panel then lets users configure section-scoped settings — a different first-page variant and the header’s or footer’s distance from its respective page edge — as well as a document-wide odd/even-page variant.

Use these controls when authors need a title-page header, mirrored odd/even running heads, or a footer placed closer to or farther from the page edge.

Edit the default header programmatically

Use headers() to get the header collection. Then use default() to get the default header, or null if the section doesn’t have one.

A header is a block-level container, so set its text on an existing paragraph:

const currentDoc = editor.currentDocument();

await currentDoc.transaction(async ({ draft }) => {
  const [section] = draft.body().sections();
  const header = section.headersAndFooters().headers().default();

  if (!header) {
    return false; // No default header configured.
  }

  const [firstBlock] = header.blocklevels();
  if (firstBlock && firstBlock.type === 'paragraph') {
    firstBlock.asTextView().setText('Confidential');
  } else {
    header.addParagraph().asTextView().setText('Confidential');
  }

  return true;
});

The examples below assume currentDoc is defined as editor.currentDocument().

Edit first-page and even-page variants

Header and footer collections expose these accessors:

• default() — Gets the default variant.
• first() — Gets the first-page variant.
• even() — Gets the even-page variant.

Footers use the same pattern through footers():

await currentDoc.transaction(async ({ draft }) => {
  const headersAndFooters = draft.body().sections()[0].headersAndFooters();

  const firstHeader = headersAndFooters.headers().first();
  if (firstHeader) {
    firstHeader.addParagraph().asTextView().setText('Title page header');
  }

  const evenHeader = headersAndFooters.headers().even();
  if (evenHeader) {
    evenHeader.addParagraph().asTextView().setText('Even page header');
  }

  const defaultFooter = headersAndFooters.footers().default();
  if (defaultFooter) {
    const [firstBlock] = defaultFooter.blocklevels();
    if (firstBlock && firstBlock.type === 'paragraph') {
      firstBlock.asTextView().setText('Page footer');
    }
  }

  return true;
});

Each variant is null when the document doesn’t define it, so check the value before you edit it.

Set header and footer spacing

Header and footer spacing is part of a section’s page margins. Use pageMargins() to read the current distances, and setPageMargins() to update the header and footer fields. Values are in points.

await currentDoc.transaction(async ({ draft }) => {
  const pageSetup = draft.body().sections()[0].pageSetup();
  const margins = pageSetup.pageMargins();

  console.log(`Header distance: ${margins.header} pt`);
  console.log(`Footer distance: ${margins.footer} pt`);

  pageSetup.setPageMargins({
    header: 36,
    footer: 36,
  });

  return true;
});

Learn more

Sections and page setup
Control page size, orientation, and margins per section.

Text and formatting
Format text inside a header or footer.