Add support for render props in Document and Page components

Author: wojtekmaj

packages/react-pdf/src/Document.spec.tsx

@@ -1,5 +1,5 @@
 import { beforeAll, describe, expect, it, vi } from 'vitest';
-import { fireEvent, getByTestId, render } from '@testing-library/react';
+import { fireEvent, getByTestId, getByText, render } from '@testing-library/react';
 import { createRef } from 'react';
 
 import Document from './Document.js';
@@ -464,6 +464,24 @@ describe('Document', () => {
 
       expect(child.dataset.scale).toBe('2');
     });
+
+    it('supports function as children', async () => {
+      const { func: onLoadSuccess, promise: onLoadSuccessPromise } = makeAsyncCallback();
+
+      const { container } = render(
+        <Document file={pdfFile.file} loading="Loading" onLoadSuccess={onLoadSuccess}>
+          {({ pdf }) => <p>{`This PDF has ${pdf.numPages} pages`}</p>}
+        </Document>,
+      );
+
+      expect.assertions(1);
+
+      await onLoadSuccessPromise;
+
+      const child = getByText(container, 'This PDF has 4 pages');
+
+      expect(child).toBeInTheDocument();
+    });
   });
 
   describe('viewer', () => {

packages/react-pdf/src/Document.tsx

@@ -33,6 +33,7 @@ import type { DocumentInitParameters } from 'pdfjs-dist/types/src/display/api.js
 import type {
   ClassName,
   DocumentCallback,
+  DocumentContextType,
   ExternalLinkRel,
   ExternalLinkTarget,
   File,
@@ -46,6 +47,7 @@ import type {
   OnPasswordCallback,
   Options,
   PasswordResponse,
+  DocumentRenderProps,
   RenderMode,
   ScrollPageIntoViewArgs,
   Source,
@@ -62,7 +64,7 @@ type OnSourceError = OnError;
 type OnSourceSuccess = () => void;
 
 export type DocumentProps = {
-  children?: React.ReactNode;
+  children?: React.ReactNode | ((props: DocumentRenderProps) => React.ReactNode);
   /**
    * Class name(s) that will be added to rendered element along with the default `react-pdf__Document`.
    *
@@ -600,7 +602,20 @@ const Document: React.ForwardRefExoticComponent<
   );
 
   function renderChildren() {
-    return <DocumentContext.Provider value={childContext}>{children}</DocumentContext.Provider>;
+    function isFulfilledContext(context: DocumentContextType): context is DocumentRenderProps {
+      return Boolean(context?.pdf);
+    }
+
+    if (!isFulfilledContext(childContext)) {
+      // Impossible, but TypeScript doesn't know that
+      throw new Error('pdf is undefined');
+    }
+
+    const resolvedChildren = typeof children === 'function' ? children(childContext) : children;
+
+    return (
+      <DocumentContext.Provider value={childContext}>{resolvedChildren}</DocumentContext.Provider>
+    );
   }
 
   function renderContent() {

packages/react-pdf/src/Page.spec.tsx

@@ -1,5 +1,5 @@
 import { beforeAll, describe, expect, it, vi } from 'vitest';
-import { fireEvent, render } from '@testing-library/react';
+import { fireEvent, getByText, render } from '@testing-library/react';
 import { createRef } from 'react';
 
 import DocumentContext from './DocumentContext.js';
@@ -732,6 +732,28 @@ describe('Page', () => {
 
       expect(annotationLayer).not.toBeInTheDocument();
     });
+
+    it('supports function as children', async () => {
+      const { func: onLoadSuccess, promise: onLoadSuccessPromise } = makeAsyncCallback();
+
+      const { container } = renderWithContext(
+        <Page onLoadSuccess={onLoadSuccess} pageIndex={0}>
+          {({ page }) => <p>{`Page ${page.pageNumber}`}</p>}
+        </Page>,
+        {
+          linkService,
+          pdf,
+        },
+      );
+
+      expect.assertions(1);
+
+      await onLoadSuccessPromise;
+
+      const child = getByText(container, 'Page 1');
+
+      expect(child).toBeInTheDocument();
+    });
   });
 
   it('requests page to be rendered without forms by default', async () => {

packages/react-pdf/src/Page.tsx

@@ -41,6 +41,8 @@ import type {
   OnRenderTextLayerError,
   OnRenderTextLayerSuccess,
   PageCallback,
+  PageContextType,
+  PageRenderProps,
   RenderMode,
 } from './shared/types.js';
 
@@ -63,7 +65,7 @@ export type PageProps = {
    * @example ref
    */
   canvasRef?: React.Ref<HTMLCanvasElement>;
-  children?: React.ReactNode;
+  children?: React.ReactNode | ((props: PageRenderProps) => React.ReactNode);
   /**
    * Class name(s) that will be added to rendered element along with the default `react-pdf__Page`.
    *
@@ -489,7 +491,7 @@ export default function Page(props: PageProps): React.ReactElement {
   const childContext = useMemo(
     () =>
       // Technically there cannot be page without pageIndex, pageNumber, rotate and scale, but TypeScript doesn't know that
-      page && isProvided(pageIndex) && pageNumber && isProvided(rotate) && isProvided(scale)
+      isProvided(pageIndex) && pageNumber && isProvided(rotate) && isProvided(scale)
         ? {
             _className,
             canvasBackground,
@@ -589,12 +591,23 @@ export default function Page(props: PageProps): React.ReactElement {
   }
 
   function renderChildren() {
+    function isFulfilledContext(context: PageContextType): context is PageRenderProps {
+      return Boolean(context?.page);
+    }
+
+    if (!isFulfilledContext(childContext)) {
+      // Impossible, but TypeScript doesn't know that
+      throw new Error('page is undefined');
+    }
+
+    const resolvedChildren = typeof children === 'function' ? children(childContext) : children;
+
     return (
       <PageContext.Provider value={childContext}>
         {renderMainLayer()}
         {renderTextLayer()}
         {renderAnnotationLayer()}
-        {children}
+        {resolvedChildren}
       </PageContext.Provider>
     );
   }

packages/react-pdf/src/shared/types.ts

@@ -175,3 +175,11 @@ export type StructTreeNodeWithExtraAttributes = StructTreeNode & {
   alt?: string;
   lang?: string;
 };
+
+export type DocumentRenderProps = Omit<NonNullable<DocumentContextType>, 'pdf'> & {
+  pdf: PDFDocumentProxy;
+};
+
+export type PageRenderProps = Omit<NonNullable<PageContextType>, 'page'> & {
+  page: PDFPageProxy;
+};