> ## Documentation Index
> Fetch the complete documentation index at: https://react-docx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Header & Footer

Headers and footers that repeat on every page of a section.

```tsx theme={"dark"}
<Section>
  <Section.Header>
    <Paragraph>My Document</Paragraph>
  </Section.Header>

  <Section.Footer>
    <Paragraph>Page <PageNumber /></Paragraph>
  </Section.Footer>

  <Paragraph>Content goes here...</Paragraph>
</Section>
```

***

## Components

| Component        | Description                     |
| ---------------- | ------------------------------- |
| `Section.Header` | Content at top of every page    |
| `Section.Footer` | Content at bottom of every page |
| `PageNumber`     | Dynamic page number field       |

***

## Basic usage

### Header only

```tsx theme={"dark"}
<Section>
  <Section.Header>
    <Paragraph className="text-gray-500 text-sm">
      Company Report 2024
    </Paragraph>
  </Section.Header>

  <H1>Introduction</H1>
  <Paragraph>...</Paragraph>
</Section>
```

### Footer only

```tsx theme={"dark"}
<Section>
  <Section.Footer>
    <Paragraph className="text-center text-xs text-gray-400">
      Confidential
    </Paragraph>
  </Section.Footer>

  <H1>Introduction</H1>
  <Paragraph>...</Paragraph>
</Section>
```

### Both

```tsx theme={"dark"}
<Section>
  <Section.Header>
    <Paragraph className="text-right">Quarterly Report</Paragraph>
  </Section.Header>

  <Section.Footer>
    <Paragraph className="text-center">
      Page <PageNumber />
    </Paragraph>
  </Section.Footer>

  <H1>Q4 Results</H1>
  <Paragraph>...</Paragraph>
</Section>
```

***

## Page numbers

The `PageNumber` component inserts dynamic page numbers.

### Current page

```tsx theme={"dark"}
<PageNumber />
// or
<PageNumber type="current" />
```

Outputs: 1, 2, 3...

### Total pages

```tsx theme={"dark"}
<PageNumber type="total" />
```

Outputs the total page count.

### Both (current of total)

```tsx theme={"dark"}
<PageNumber type="both" />
```

Outputs: "Page 1 of 10"

### Custom format

```tsx theme={"dark"}
<PageNumber format="{current} / {total}" />
```

Outputs: "1 / 10"

```tsx theme={"dark"}
<PageNumber format="- {current} -" />
```

Outputs: "- 1 -"

***

## Styling

Headers and footers support Tailwind classes.

### Right-aligned header

```tsx theme={"dark"}
<Section.Header>
  <Paragraph className="text-right text-sm text-gray-500">
    Document Title
  </Paragraph>
</Section.Header>
```

### Centered footer with styling

```tsx theme={"dark"}
<Section.Footer>
  <Paragraph className="text-center text-xs text-gray-400">
    Page <PageNumber /> of <PageNumber type="total" />
  </Paragraph>
</Section.Footer>
```

### Multiple lines

```tsx theme={"dark"}
<Section.Header>
  <Paragraph className="font-bold">ACME Corporation</Paragraph>
  <Paragraph className="text-sm text-gray-500">
    Annual Report 2024
  </Paragraph>
</Section.Header>
```

***

## Header/footer spacing

Control distance from page edge with margin options:

```tsx theme={"dark"}
<Section
  margins={{
    top: "1in",
    bottom: "1in",
    header: "0.5in",  // Distance from top edge to header
    footer: "0.5in",  // Distance from bottom edge to footer
  }}
>
  <Section.Header>...</Section.Header>
  <Section.Footer>...</Section.Footer>
</Section>
```

***

## Allowed content

Headers and footers can contain:

| Component              | Supported              |
| ---------------------- | ---------------------- |
| `Paragraph`            | Yes                    |
| `H1`-`H6`              | Yes                    |
| `Text`                 | Yes                    |
| `Bold`, `Italic`, etc. | Yes (inside Paragraph) |
| `PageNumber`           | Yes                    |
| `Table`                | No                     |
| `Image`                | No                     |
| `List`                 | No                     |

***

## Common patterns

### Document title + page number

```tsx theme={"dark"}
<Section.Header>
  <Paragraph className="text-sm text-gray-500">
    Project Proposal
  </Paragraph>
</Section.Header>

<Section.Footer>
  <Paragraph className="text-center text-xs">
    <PageNumber type="both" />
  </Paragraph>
</Section.Footer>
```

### Company branding

```tsx theme={"dark"}
<Section.Header>
  <Paragraph>
    <Text className="font-bold">ACME Corp</Text>
    <Text className="text-gray-500"> | Internal Document</Text>
  </Paragraph>
</Section.Header>
```

### Legal footer

```tsx theme={"dark"}
<Section.Footer>
  <Paragraph className="text-xs text-gray-400 text-center">
    Confidential - Do not distribute
  </Paragraph>
  <Paragraph className="text-xs text-gray-400 text-center">
    Page <PageNumber /> of <PageNumber type="total" />
  </Paragraph>
</Section.Footer>
```

### Left and right aligned (using tabs)

```tsx theme={"dark"}
<Section.Footer>
  <Paragraph>
    Confidential<Tab /><Tab /><Tab />Page <PageNumber />
  </Paragraph>
</Section.Footer>
```

***

## Different headers per section

Each section has its own header/footer. Use multiple sections for different headers:

```tsx theme={"dark"}
<Document>
  {/* Title page - no header/footer */}
  <Section>
    <H1 className="text-center mt-48">Annual Report</H1>
    <Paragraph className="text-center">2024</Paragraph>
  </Section>

  {/* Main content - with header/footer */}
  <Section>
    <Section.Header>
      <Paragraph className="text-gray-500">Annual Report 2024</Paragraph>
    </Section.Header>

    <Section.Footer>
      <Paragraph className="text-center">
        <PageNumber type="both" />
      </Paragraph>
    </Section.Footer>

    <H1>Executive Summary</H1>
    <Paragraph>...</Paragraph>
  </Section>

  {/* Appendix - different header */}
  <Section>
    <Section.Header>
      <Paragraph className="text-gray-500">Appendix</Paragraph>
    </Section.Header>

    <H1>Appendix A: Data Tables</H1>
    <Table>...</Table>
  </Section>
</Document>
```

***

## Full example

```tsx theme={"dark"}
import {
  render,
  Document,
  Section,
  H1,
  H2,
  Paragraph,
  Text,
  PageNumber,
} from "@cordel/react-docx";

const Report = () => (
  <Document>
    <Section
      margins={{
        top: "1in",
        bottom: "1in",
        left: "1.25in",
        right: "1in",
        header: "0.5in",
        footer: "0.5in",
      }}
    >
      <Section.Header>
        <Paragraph className="text-right text-sm text-gray-500">
          <Text className="font-bold">ACME Corp</Text> - Q4 Report
        </Paragraph>
      </Section.Header>

      <Section.Footer>
        <Paragraph className="text-center text-xs text-gray-400">
          Confidential | Page <PageNumber /> of <PageNumber type="total" />
        </Paragraph>
      </Section.Footer>

      <H1>Quarterly Report</H1>
      <Paragraph>
        This report summarizes Q4 2024 performance...
      </Paragraph>

      <H2>Financial Highlights</H2>
      <Paragraph>
        Revenue increased by 15% compared to Q3...
      </Paragraph>
    </Section>
  </Document>
);

await render(<Report />, "./report.docx");
```