Fix method update and add more examples (#78)

* remove node 14 from ci * fix wrong default method that should be save * update README and rename to examples folder * update readme * update examples and api docs * update examples and API docs * run lint * update api docs
ivmarcos · Sep 2, 2023 · d94c930 · d94c930
1 parent 6ee98c4
commit d94c930
Show file tree

Hide file tree

Showing 26 changed files with 454 additions and 739 deletions.
diff --git a/README.md b/README.md
@@ -18,24 +18,36 @@ $ npm install react-to-pdf
 - [@react-pdf/renderer](https://www.npmjs.com/package/@react-pdf/renderer) - React renderer to create PDF files on the browser and server
 - [react-pdf](https://www.npmjs.com/package/react-pdf) - Display PDFs in your React app as easily as if they were images.
 
+
+## Examples
+
+- [Code Sandbox demo](https://codesandbox.io/s/ancient-violet-sznj9q?file=/src/App.tsx)
+- [Using `usePDF` hook](blob/main/examples/ExampleUsePDF.tsx) 
+- [Using default function](blob/main/examples/ExampleFunction.tsx) 
+- [Multipage support](blob/main/examples/ExampleMultipage.tsx) 
+- [Advanced options](blob/main/examples/ExampleAdvanced.tsx) 
+
 ## Usage
 
-**Using hook**
+**Using `usePDF` hook**
 
 ```jsx
 import { usePDF } from 'react-to-pdf';
 
 const Component = () => {
    const { toPDF, targetRef } = usePDF({filename: 'page.pdf'});
    return (
-      <button onClick={toPDF}>Download PDF</button>
-      <div ref={targetRef}>
-         Content to be generated to PDF
+      <div>
+         <button onClick={() => toPDF()}>Download PDF</button>
+         <div ref={targetRef}>
+            Content to be generated to PDF
+         </div>
       </div>
    )
 }
 ```
 
+
 **Using default function**
 
 ```jsx
@@ -45,9 +57,11 @@ import generatePDF from 'react-to-pdf';
 const Component = () => {
    const targetRef = useRef();
    return (
-      <button onClick={() => generatePDF(targetRef, {filename: 'page.pdf'})}>Download PDF</button>
-      <div ref={targetRef}>
-         Content to be included in the PDF
+      <div>
+         <button onClick={() => generatePDF(targetRef, {filename: 'page.pdf'})}>Download PDF</button>
+         <div ref={targetRef}>
+            Content to be included in the PDF
+         </div>
       </div>
    )
 }
@@ -79,8 +93,9 @@ const options = {
       mimeType: 'image/png'
       qualityRatio: 1
    },
-   // customize any value passed to the jsPDF instance and html2canvas
-   // function
+   // Customize any value passed to the jsPDF instance and html2canvas
+   // function. You probably will not need this and things can break, 
+   // so use with caution.
    overrides: {
       // see https://artskydj.github.io/jsPDF/docs/jsPDF.html for more options
       pdf: {
@@ -93,13 +108,16 @@ const options = {
    },
 };
 
+// you can use a function to return the target element besides using React refs
+const getTargetElement = () => document.getElementById('content-id');
+
 const Component = () => {
-   // you can use a function to return the target element besides using React refs
-   const getTargetElement = () => document.getElementById('content-id');
    return (
-      <button onClick={() => generatePDF(getTargetElement, options)}>Generate PDF</button>
-      <div id="content-id">
-         Content to be generated to PDF
+      <div>
+         <button onClick={() => generatePDF(getTargetElement, options)}>Generate PDF</button>
+         <div id="content-id">
+            Content to be generated to PDF
+         </div>
       </div>
    );
 }

diff --git a/docs/README.md b/docs/README.md
@@ -2,7 +2,7 @@ react-to-pdf / [Modules](modules.md)
 
 # React to PDF
 
-Easily create pdf documents from React components.
+Easily create PDF documents from React components.
 
 ## Install
 
@@ -12,85 +12,113 @@ $ npm install react-to-pdf
 
 ## Important Notes
 
+- Not vectorized - the pdf is created from a screenshot of the component and therefore is not vectorized. If you are looking for something more advanced to generate pdf using React components, please check out other popular alternatives packages listed below.
 - No SSR
-- Single page
-- Not vectorized - the pdf is created from a screenshot of the component and therefore is not vectorized. If you are looking for something more advanced for generating pdf using React components, please check out other popular alternatives packages listed below.
 
 ## Alternatives and Similars Packages
 
-* [@react-pdf/renderer](https://www.npmjs.com/package/@react-pdf/renderer) - React renderer for creating PDF files on the browser and server
-* [react-pdf](https://www.npmjs.com/package/react-pdf) - Display PDFs in your React app as easily as if they were images.
+- [@react-pdf/renderer](https://www.npmjs.com/package/@react-pdf/renderer) - React renderer to create PDF files on the browser and server
+- [react-pdf](https://www.npmjs.com/package/react-pdf) - Display PDFs in your React app as easily as if they were images.
 
 ## Examples
 
-https://codesandbox.io/s/l2l4pz0jyl
+- [Code Sandbox demo](https://codesandbox.io/s/ancient-violet-sznj9q?file=/src/App.tsx)
+- [Using `usePDF` hook](blob/main/examples/ExampleUsePDF.tsx) 
+- [Using default function](blob/main/examples/ExampleFunction.tsx) 
+- [Multipage support](blob/main/examples/ExampleMultipage.tsx) 
+- [Advanced options](blob/main/examples/ExampleAdvanced.tsx) 
 
 ## Usage
 
-**Using hook**
+**Using `usePDF` hook**
 
 ```jsx
-   import { usePDF } from 'react-to-pdf'
+import { usePDF } from 'react-to-pdf';
 
 const Component = () => {
-   const { toPDF, targetRef } = usePDF();
-
-return (
-   <button onClick={toPDF}>Generate PDF</button>
-   <div ref={targetRef}>
-     Content to be included in the PDF
-   </div>
-)
-
+   const { toPDF, targetRef } = usePDF({filename: 'page.pdf'});
+   return (
+      <div>
+         <button onClick={() => toPDF()}>Download PDF</button>
+         <div ref={targetRef}>
+            Content to be generated to PDF
+         </div>
+      </div>
+   )
 }
-
 ```
 
-**Using generatedPDF function**
-
-**Using outer target ref**
+**Using default function**
 
 ```jsx
-   import { generatePDF } from 'react-to-pdf'
+import { useRef } from 'react';
+import generatePDF from 'react-to-pdf';
 
 const Component = () => {
-    const targetRef = React.createRef();
-return (
-   <button onClick={() => generatePDF(targetRef)}>Generate PDF</button>
-   <div ref={targetRef}>
-     Content to be included in the PDF
-   </div>
-)
-
+   const targetRef = useRef();
+   return (
+      <div>
+         <button onClick={() => generatePDF(targetRef, {filename: 'page.pdf'})}>Download PDF</button>
+         <div ref={targetRef}>
+            Content to be included in the PDF
+         </div>
+      </div>
+   )
 }
 ```
 
 **Advanced options**
+
 ```jsx
-const ref = React.createRef();
+import generatePDF, { Resolution, Margin } from 'react-to-pdf';
+
 const options = {
-    orientation: 'landscape',
-    unit: 'in',
-    format: [4,2]
+   // default is `save`
+   method: 'open',
+   // default is Resolution.MEDIUM = 3, which should be enough, higher values
+   // increases the image quality but also the size of the PDF, so be careful
+   // using values higher than 10 when having multiple pages generated, it
+   // might cause the page to crash or hang.
+   resolution: Resolution.HIGH,
+   page: {
+      // margin is in MM, default is Margin.NONE = 0
+      margin: Margin.SMALL,
+      // default is 'A4'
+      format: 'letter',
+      // default is 'portrait'
+      orientation: 'landscape',
+   },
+   canvas: {
+      // default is 'image/jpeg' for better size performance
+      mimeType: 'image/png'
+      qualityRatio: 1
+   },
+   // Customize any value passed to the jsPDF instance and html2canvas
+   // function. You probably will not need this and things can break, 
+   // so use with caution.
+   overrides: {
+      // see https://artskydj.github.io/jsPDF/docs/jsPDF.html for more options
+      pdf: {
+         compress: true
+      },
+      // see https://html2canvas.hertzen.com/configuration for more options
+      canvas: {
+         useCORS: false
+      }
+   },
 };
-<div>
-    <ReactToPdf targetRef={ref} filename="div-blue.pdf" options={options} x={.5} y={.5} scale={0.8}>
-        {({toPdf}) => (
-            <button onClick={toPdf}>Generate pdf</button>
-        )}
-    </ReactToPdf>
-    <div style={{width: 500, height: 500, background: 'blue'}} ref={ref}/>
-</div>
-```
 
-## Props
-
-|Prop name        |Type               |Default            |Description
-|-----------------|-------------------|-------------------|--------------------------------
-|filename         | `string`          | `'download.pdf'`  | Name of the pdf file
-|targetRef        | `RefObject`       |                   | [React ref](https://reactjs.org/docs/refs-and-the-dom.html) for the target component (use this or inner target reference)
-|x                | `number`          |         0         | X position in document
-|y                | `number`          |         0         | Y position in document
-|options          | `object`          |    `undefined`    | options for the jsPdf document - [view more details](https://rawgit.com/MrRio/jsPDF/master/docs/)
-|onComplete       | `function`        |    `undefined`    | callback executed when process is finished
-|scale            | `number`          |    1              | Image scaling
+// you can use a function to return the target element besides using React refs
+const getTargetElement = () => document.getElementById('content-id');
+
+const Component = () => {
+   return (
+      <div>
+         <button onClick={() => generatePDF(getTargetElement, options)}>Generate PDF</button>
+         <div id="content-id">
+            Content to be generated to PDF
+         </div>
+      </div>
+   );
+}
+```
diff --git a/docs/enums/constants.Margin.md b/docs/enums/constants.Margin.md
@@ -21,7 +21,7 @@
 
 #### Defined in
 
-constants.ts:17
+[constants.ts:17](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L17)
 
 ___
 
@@ -31,7 +31,7 @@ ___
 
 #### Defined in
 
-constants.ts:16
+[constants.ts:16](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L16)
 
 ___
 
@@ -41,7 +41,7 @@ ___
 
 #### Defined in
 
-constants.ts:14
+[constants.ts:14](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L14)
 
 ___
 
@@ -51,4 +51,4 @@ ___
 
 #### Defined in
 
-constants.ts:15
+[constants.ts:15](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L15)
diff --git a/docs/enums/constants.Resolution.md b/docs/enums/constants.Resolution.md
@@ -22,7 +22,7 @@
 
 #### Defined in
 
-constants.ts:10
+[constants.ts:10](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L10)
 
 ___
 
@@ -32,7 +32,7 @@ ___
 
 #### Defined in
 
-constants.ts:9
+[constants.ts:9](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L9)
 
 ___
 
@@ -42,7 +42,7 @@ ___
 
 #### Defined in
 
-constants.ts:6
+[constants.ts:6](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L6)
 
 ___
 
@@ -52,7 +52,7 @@ ___
 
 #### Defined in
 
-constants.ts:8
+[constants.ts:8](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L8)
 
 ___
 
@@ -62,4 +62,4 @@ ___
 
 #### Defined in
 
-constants.ts:7
+[constants.ts:7](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L7)
diff --git a/docs/modules/constants.md b/docs/modules/constants.md
@@ -22,7 +22,7 @@
 
 #### Defined in
 
-constants.ts:20
+[constants.ts:20](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L20)
 
 ___
 
@@ -32,4 +32,4 @@ ___
 
 #### Defined in
 
-constants.ts:3
+[constants.ts:3](https://github.com/ivmarcos/react-to-pdf/blob/36bd08b/src/constants.ts#L3)