diegomura / diegomura/react-pdf

RFC: `layout` prop on Page for repeating page chrome

Open
#3,499 9 comments 2 reactions 1 assignee Claimed by @carlobeltrame View on GitHub
Dominant language
TypeScript
Stars
16.8k
Forks
1.3k
Avg merge
5h 6m
Merged PRs (30d)
52

Description

While working on a major pagination refactor (long running effort, the new engine paginates in a single O(N) pass instead of relayouting pages over and over), I landed on an API idea I want to collect thoughts on before building it: a `layout` prop on `Page`.

## The idea

You pass a component to `Page` that describes the repeating chrome of every page. Where it renders `{children}` is where the page content flows:

```jsx
const PageLayout = ({ children, pageNumber }) => (
<>



{children}


`Page ${pageNumber}`} />


);

{content}

```

## Why

`fixed` is probably the most confused API in react-pdf. It repeats an element on every page, but it doesn't reserve space for it, so footers overlap content unless you compensate with page padding by hand.

With `layout` the chrome reserves its space by construction. The content region is simply whatever space is left, measured by flexbox like everything else. It also expresses things `fixed` never could: a sidebar next to the content on every page, or a frame wrapping the content region.

Since the component receives page props, per page variants (different first page, odd/even mirroring, headers that change height) work out of the box.

This is the same model as InDesign parent pages or QuestPDF slots, and the `{ children }` signature should feel familiar from Next.js layouts.

## What happens to `fixed`

It stays, but only for the "render on top of every page" case (watermarks, stamps). `layout` becomes the story for headers, footers and anything that should take up space. This would ship as part of the pagination rewrite major, so one breaking release, one migration.

Curious what people think, both about the API shape and about use cases it should cover.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.