Requested Feature #3341 = breakWhenNeeded

[caticHarun]

closes #3341

This feature adds a property "breakWhenNeeded".

If breakWhenNeeded=true and element cannot fit on the page, then it adds a page break before

The main difference between wrap=false and breakWhenNeeded=true is that in wrap={false} the element is limited on one page. Whereas in breakWhenNeeded=true, it only adds a break before and it continues on as it should

[changeset-bot]

🦋 Changeset detected

Latest commit: 62dac5c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@react-pdf/layout	Minor
@react-pdf/renderer	Minor
@react-pdf/types	Minor
@react-pdf/render	Patch
@react-pdf/math	Major
@react-pdf/mermaid	Major
next-14	Patch
next-15	Patch
@react-pdf/vite-example	Patch
@react-pdf/font	Patch
@react-pdf/stylesheet	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[diegomura]

I don't think I understand the difference between break and breakWhenNeeded (nor I like the name of the prop too much :))

[caticHarun]

break=true always makes a page break

But breakWhenNeeded adds a page break if the element is going to wrap on another page. But if that element is bigger than the whole page (e.g if is is bigger than the A4 Format), then it continues normally (with a page break before)

[caticHarun]

Here is the use case I am going for.

Imagine an invoice style application, that makes pdfs

You have headers, products and lastly total.

If you have a couple of items, then you want the total on the same page.

But if you have a bit more items, the total gets wrapped on another page

The goal is to add a page break if it wraps, and if it does not, then leave it on the same page

Currently you can do this with wrap=false, but the issue is, when the element is too big to fit on one page, it tries to squeze everything on one paper which can lead to this:

And with breakWhenNeeded

[caticHarun]

Name of the prop is not important, it can always be changed :)

[caticHarun]

let me know how to proceed

[piotrbaldych-cr]

@diegomura this is such a simple change but such important add-on for multiple use-cases like tables or long lists of complex elements. What can we do to make it merged in?

@caticHarun thank you so much for this!

[raffaeldp]

Thank you so much for this PR. I would in fact need exactly this for my app. It would be so great to see it merged :)

Also, if you do not like the name @diegomura, this could maybe become a default behavior of wrap=false. Like if we do not have enough space on the current page, we go to the next one, but if the component is bigger than the whole next page, we break and go to the next one ?
That could be a solution if there is no usecase of not breaking when component is bigger than one page.