Print React Components

Common errors

• TypeError: Cannot read properties of null (reading 'current') at content

  cause The `content` option in `useReactToPrint` returned `null` or `undefined`, meaning the `ref` to the component to be printed was not yet available or was incorrectly passed.
  fix Ensure the `ref` (e.g., `componentRef`) is correctly attached to the DOM element you intend to print and that the element is mounted when the print function is invoked. Check the `content` callback always returns a valid DOM element.

• Styles are missing or incorrect in the printed output.

  cause Browser print stylesheets (`@media print`) are not being applied, or dynamic styles (e.g., CSS-in-JS) are not being transferred to the print iframe.
  fix Use the `pageStyle` option to inject specific print styles. For dynamic styles, ensure they are rendered into static CSS that can be copied. Check if `ignoreGlobalStyles` is inadvertently set to `true`.

• Prints a blank page or only part of the content.

  cause The element referenced by `contentRef` might be hidden by CSS, or its dimensions are zero in the print context, or JavaScript rendering is incomplete before print.
  fix Inspect the `print` iframe (by setting `preserveAfterPrint: true`) to see what content it received. Ensure the component to be printed has visible dimensions and styles that allow it to be rendered in a print-friendly manner. Use `onBeforePrint` to delay printing until content is fully rendered.

• ReferenceError: ReactToPrint is not defined

  cause Attempting to use the `ReactToPrint` class component with an incorrect named import, or in an environment where it's not available.
  fix If using the class component, ensure it's imported as a default import: `import ReactToPrint from 'react-to-print';`. For new code, prefer the `useReactToPrint` hook: `import { useReactToPrint } from 'react-to-print';`.

Warnings

• breaking Version 3.x introduced a significant API change, shifting from a class component (`ReactToPrint`) to a functional hook (`useReactToPrint`) as the primary interface. While the class component is still available, the hook is the recommended and more modern approach.
  Fix: Migrate class-based `ReactToPrint` usage to the `useReactToPrint` hook for functional components. Ensure `content` option returns the DOM node to be printed.
• gotcha External CSS files and global styles might not apply correctly to the printed content if they are not explicitly loaded or if the `ignoreGlobalStyles` option is used incorrectly. Browser print styles often differ from screen styles.
  Fix: Use the `pageStyle` option for custom print CSS, or ensure `<link>` and `<style>` tags are properly handled by the browser's print engine. For external stylesheets, ensure they are accessible and loaded within the print iframe. Consider `onBeforePrint` to dynamically inject print-specific styles.
• gotcha When using `content: () => componentRef.current`, ensure that `componentRef.current` is not `null` or `undefined` at the time `handlePrint` is called. This can happen if the component is unmounted or the ref isn't properly attached yet.
  Fix: Always check for `componentRef.current` before returning it in the `content` callback, e.g., `content: () => componentRef.current || document.createElement('div')` or ensure the component is mounted before triggering print. The hook's internal logic handles a null return by showing an error.
• gotcha The `onAfterPrint` callback triggers regardless of whether the user chose to print or canceled the print dialog. This can lead to unexpected side effects if state changes are based solely on this callback.
  Fix: If specific actions need to occur only upon successful print, you might need to implement a more complex tracking mechanism, potentially by combining `onBeforePrint` and a timeout, or accepting the browser's native behavior.
• gotcha Printing content with shadow DOMs (e.g., from Web Components) can be slow or lead to missing styles if `copyShadowRoots` is not enabled or used improperly, especially for large documents.
  Fix: Enable the `copyShadowRoots: true` option if your content includes shadow DOMs. Be aware of potential performance impacts on very large documents and test thoroughly.

Install

• npm install react-to-print npm
• yarn add react-to-print yarn
• pnpm add react-to-print pnpm

Imports

• useReactToPrint
  wrong:

  const useReactToPrint = require('react-to-print');

  correct:

  import { useReactToPrint } from 'react-to-print';

  Primary hook for functional components. Package is ESM-first; CommonJS `require` is not the idiomatic way.
• ReactToPrint
  wrong:

  import { ReactToPrint } from 'react-to-print';

  correct:

  import ReactToPrint from 'react-to-print';

  Class component wrapper (legacy API). While still supported, `useReactToPrint` is recommended for new development.
• RefObject

  import React, { useRef, type RefObject } from 'react';
  // ...or for use in a function:
  const contentRef = useRef<HTMLDivElement>(null);

  While `RefObject` is a React type, it's crucial for correct TypeScript usage with `contentRef` option, ensuring type safety when referencing DOM elements to be printed.

Quickstart

Demonstrates basic usage of `useReactToPrint` hook to print a component's content, including ref setup, print options, and lifecycle callbacks.

import { useReactToPrint } from 'react-to-print';
import React, { useRef } from 'react';

const MyPrintableComponent = () => {
  const componentRef = useRef<HTMLDivElement>(null);

  const handlePrint = useReactToPrint({
    content: () => componentRef.current,
    documentTitle: 'My Custom Print Document',
    pageStyle: '@page { size: auto; margin: 25mm; } @media print { body { -webkit-print-color-adjust: exact; } }',
    onBeforePrint: async () => {
      console.log('onBeforePrint callback!');
      // Potentially fetch data or modify component state before print
      await new Promise(resolve => setTimeout(resolve, 500)); // Simulate async work
    },
    onAfterPrint: () => console.log('onAfterPrint callback!')
  });

  return (
    <div>
      <button onClick={handlePrint}>Print this out!</button>
      <div ref={componentRef} style={{ padding: '20px', border: '1px solid #ccc' }}>
        <h1>Document Title</h1>
        <p>This is the content that will be printed. It can be any React component's output.</p>
        <p>Example: User ID: {process.env.REACT_APP_USER_ID ?? 'N/A'}</p>
        <ul>
          <li>Item 1</li>
          <li>Item 2</li>
          <li>Item 3</li>
        </ul>
      </div>
    </div>
  );
};

export default MyPrintableComponent;