Skip to content

Commit 6028322

Browse files
eKoopmanseKoopmans
committed
Add pagebreak updates to the readme
1 parent 2de9985 commit 6028322

File tree

1 file changed

+46
-15
lines changed

1 file changed

+46
-15
lines changed

‎README.md

Lines changed: 46 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -106,25 +106,56 @@ html2pdf(element, opt);
106106

107107
The `opt` parameter has the following optional fields:
108108

109-
|Name |Type |Default |Description |
110-
|------------|----------------|------------------------------|------------------------------------------------------------------------------------------------------------|
111-
|margin |number or array |0 |PDF margin (in jsPDF units). Can be a single number, `[vMargin, hMargin]`, or `[top, left, bottom, right]`. |
112-
|filename |string |'file.pdf' |The default filename of the exported PDF. |
113-
|image |object |{type: 'jpeg', quality: 0.95} |The image type and quality used to generate the PDF. See the Extra Features section below. |
114-
|enableLinks |boolean |true |If enabled, PDF hyperlinks are automatically added ontop of all anchor tags. |
115-
|html2canvas |object |{ } |Configuration options sent directly to `html2canvas` ([see here](https://html2canvas.hertzen.com/configuration) for usage).|
116-
|jsPDF |object |{ } |Configuration options sent directly to `jsPDF` ([see here](http://rawgit.com/MrRio/jsPDF/master/docs/jsPDF.html) for usage).|
109+
|Name |Type |Default |Description |
110+
|------------|----------------|--------------------------------|------------------------------------------------------------------------------------------------------------|
111+
|margin |number or array |`0` |PDF margin (in jsPDF units). Can be a single number, `[vMargin, hMargin]`, or `[top, left, bottom, right]`. |
112+
|filename |string |`'file.pdf'` |The default filename of the exported PDF. |
113+
|pagebreak |object |`{mode: ['css', 'legacy']}` |Controls the pagebreak behaviour on the page. See [Page-breaks](#page-breaks) below. |
114+
|image |object |`{type: 'jpeg', quality: 0.95}` |The image type and quality used to generate the PDF. See [Image type and quality](#image-type-and-quality) below.|
115+
|enableLinks |boolean |`true` |If enabled, PDF hyperlinks are automatically added ontop of all anchor tags. |
116+
|html2canvas |object |`{ }` |Configuration options sent directly to `html2canvas` ([see here](https://html2canvas.hertzen.com/configuration) for usage).|
117+
|jsPDF |object |`{ }` |Configuration options sent directly to `jsPDF` ([see here](http://rawgit.com/MrRio/jsPDF/master/docs/jsPDF.html) for usage).|
117118

118119
### Page-breaks
119120

120-
You may add `html2pdf`-specific page-breaks to your document by adding the CSS class `html2pdf__page-break` to any element (normally an empty `div`). For React elements, use `className=html2pdf__page-break`. During PDF creation, these elements will be given a height calculated to fill the remainder of the PDF page that they are on. Example usage:
121+
html2pdf has the ability to automatically add page-breaks to clean up your document. Page-breaks can be added by CSS styles, set on individual elements using selectors, or avoided from breaking inside all elements (`avoid-all` mode).
121122

122-
```html
123-
<div id="element-to-print">
124-
<span>I'm on page 1!</span>
125-
<div class="html2pdf__page-break"></div>
126-
<span>I'm on page 2!</span>
127-
</div>
123+
By default, html2pdf will respect most CSS [`break-before`](https://developer.mozilla.org/en-US/docs/Web/CSS/break-before), [`break-after`](https://developer.mozilla.org/en-US/docs/Web/CSS/break-after), and [`break-inside`](https://developer.mozilla.org/en-US/docs/Web/CSS/break-inside) rules, and also add page-breaks after any element with class `html2pdf__page-break` (for legacy purposes).
124+
125+
#### Page-break settings
126+
127+
|Setting |Type |Default |Description |
128+
|----------|----------------|--------------------|------------|
129+
|mode |string or array |`['css', 'legacy']` |The mode(s) on which to automatically add page-breaks. One or more of `'avoid-all'`, `'css'`, and `'legacy'`. |
130+
|before |string or array |`[]` |CSS selectors for which to add page-breaks before each element. Can be a specific element with an ID (`'#myID'`), all elements of a type (e.g. `'img'`), all of a class (`'.myClass'`), or even `'*'` to match every element. |
131+
|after |string or array |`[]` |Like 'before', but adds a page-break immediately after the element. |
132+
|avoid |string or array |`[]` |Like 'before', but avoids page-breaks on these elements. You can enable this feature on every element using the 'avoid-all' mode. |
133+
134+
#### Page-break modes
135+
136+
| Mode | Description |
137+
|-----------|-------------|
138+
| avoid-all | Automatically adds page-breaks to avoid splitting any elements across pages. |
139+
| css | Adds page-breaks according to the CSS `break-before`, `break-after`, and `break-inside` properties. Only recognizes `always/left/right` for before/after, and `avoid` for inside. |
140+
| legacy | Adds page-breaks after elements with class `html2pdf__page-break`. This feature may be removed in the future. |
141+
142+
#### Example usage
143+
144+
```js
145+
// Avoid page-breaks on all elements, and add one before #page2el.
146+
html2pdf().set({
147+
pagebreak: { mode: 'avoid-all', before: '#page2el' }
148+
});
149+
150+
// Enable all 'modes', with no explicit elements.
151+
html2pdf().set({
152+
pagebreak: { mode: ['avoid-all', 'css', 'legacy'] }
153+
});
154+
155+
// No modes, only explicit elements.
156+
html2pdf().set({
157+
pagebreak: { before: '.beforeClass', after: ['#after1', '#after2'], avoid: 'img' }
158+
});
128159
```
129160

130161
### Image type and quality

0 commit comments

Comments
 (0)