---
title: "Headers and footers"
canonical_url: "https://www.nutrient.io/guides/document-authoring/page-layout/headers-and-footers/"
md_url: "https://www.nutrient.io/guides/document-authoring/page-layout/headers-and-footers.md"
last_updated: "2026-07-09T00:00:00.000Z"
description: "Edit header and footer content in Document Authoring by accessing a section’s default, first-page, and even-page header and footer containers."
---

# 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](https://www.nutrient.io/guides/document-authoring/editing-content/programmatic-editing.md), use [`Section.headersAndFooters()`](https://www.nutrient.io/api/document-authoring/types/programmatic/section/#headersandfooters) to access them programmatically.

As of [1.17.0](https://www.nutrient.io/guides/document-authoring/changelog.md#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](https://www.nutrient.io/guides/document-authoring/editing-content/images-and-shapes.md) and [footnotes and endnotes](https://www.nutrient.io/guides/document-authoring/editing-content/footnotes-and-endnotes.md): 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](https://www.nutrient.io/sdk/document-authoring/getting-started.md) 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()`](https://www.nutrient.io/api/document-authoring/types/programmatic/headersandfooters/#headers) to get the header collection. Then use [`default()`](https://www.nutrient.io/api/document-authoring/types/programmatic/headersfooters/#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:

```js

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()`](https://www.nutrient.io/api/document-authoring/types/programmatic/headersfooters/#default) — Gets the default variant.

- [`first()`](https://www.nutrient.io/api/document-authoring/types/programmatic/headersfooters/#first) — Gets the first-page variant.

- [`even()`](https://www.nutrient.io/api/document-authoring/types/programmatic/headersfooters/#even) — Gets the even-page variant.

Footers use the same pattern through [`footers()`](https://www.nutrient.io/api/document-authoring/types/programmatic/headersandfooters/#footers):

```js

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()`](https://www.nutrient.io/api/document-authoring/types/programmatic/pagesetup/#pagemargins) to read the current distances, and [`setPageMargins()`](https://www.nutrient.io/api/document-authoring/types/programmatic/pagesetup/#setpagemargins) to update the `header` and `footer` fields. Values are in points.

```js

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](https://www.nutrient.io/guides/document-authoring/page-layout/sections-and-page-setup.md)**\
Control page size, orientation, and margins per section.

**[Text and formatting](https://www.nutrient.io/guides/document-authoring/editing-content/text-and-formatting.md)**\
Format text inside a header or footer.
---

## Related pages

- [Set up sections and pages](/guides/document-authoring/page-layout/sections-and-page-setup.md)