tessl/npm-react-pdf
Display PDFs in your React app as easily as if they were images.
—
Pending
page-rendering.mddocs/
Page Rendering
Page rendering system with multiple layer support and extensive customization options for displaying individual PDF pages with text selection, annotations, and forms.
Capabilities
Page Component
Renders individual PDF pages with multiple layers and comprehensive customization options.
/**
* Displays a PDF page with configurable layers and rendering options
* Should be placed inside <Document /> or passed explicit pdf prop
* @param props - Page configuration and event handlers
* @returns React element rendering the PDF page
*/
function Page(props: PageProps): React.ReactElement;
interface PageProps {
/** Which page to display by page number (1-based) */
pageNumber?: number;
/** Which page to display by page index (0-based) */
pageIndex?: number;
/** Page scale factor */
scale?: number;
/** Page rotation in degrees (90, 180, 270) */
rotate?: number | null;
/** Fixed width in pixels (overrides scale if both provided) */
width?: number;
/** Fixed height in pixels (overrides scale if both provided) */
height?: number;
/** Rendering mode for the page */
renderMode?: RenderMode;
/** Whether to render text layer for selection and accessibility */
renderTextLayer?: boolean;
/** Whether to render annotations (links, forms, etc.) */
renderAnnotationLayer?: boolean;
/** Whether to render interactive forms */
renderForms?: boolean;
/** Custom renderer component for 'custom' render mode */
customRenderer?: CustomRenderer;
/** Custom text renderer function */
customTextRenderer?: CustomTextRenderer;
/** Device pixel ratio for high DPI displays */
devicePixelRatio?: number;
/** Canvas background color */
canvasBackground?: string;
/** Function called when page loads successfully */
onLoadSuccess?: (page: PageCallback) => void;
/** Function called when page fails to load */
onLoadError?: (error: Error) => void;
/** Function called when page renders successfully */
onRenderSuccess?: () => void;
/** Function called when page fails to render */
onRenderError?: (error: Error) => void;
/** Function called when text layer renders successfully */
onRenderTextLayerSuccess?: () => void;
/** Function called when text layer fails to render */
onRenderTextLayerError?: (error: Error) => void;
/** Function called when annotation layer renders successfully */
onRenderAnnotationLayerSuccess?: () => void;
/** Function called when annotation layer fails to render */
onRenderAnnotationLayerError?: (error: unknown) => void;
/** Function called when text content is loaded successfully */
onGetTextSuccess?: (textContent: TextContent) => void;
/** Function called when text content fails to load */
onGetTextError?: (error: Error) => void;
/** Function called when annotations are loaded successfully */
onGetAnnotationsSuccess?: (annotations: Annotations) => void;
/** Function called when annotations fail to load */
onGetAnnotationsError?: (error: Error) => void;
/** Child components or render function */
children?: React.ReactNode | ((props: PageRenderProps) => React.ReactNode);
/** Class names for styling */
className?: ClassName;
/** Custom error message or component */
error?: NodeOrRenderer;
/** Custom loading message or component */
loading?: NodeOrRenderer;
/** Custom no-data message or component */
noData?: NodeOrRenderer;
/** React ref for the main page div */
inputRef?: React.Ref<HTMLDivElement | null>;
/** React ref for the canvas element */
canvasRef?: React.Ref<HTMLCanvasElement>;
}Usage Examples:
import { Document, Page } from "react-pdf";
// Basic page rendering
function BasicPageViewer() {
return (
<Document file="sample.pdf">
<Page pageNumber={1} />
</Document>
);
}
// Page with custom size and layers
function CustomPageViewer() {
return (
<Document file="sample.pdf">
<Page
pageNumber={1}
width={600}
renderTextLayer={true}
renderAnnotationLayer={true}
renderForms={true}
onLoadSuccess={(page) => {
console.log('Page loaded:', page.width, 'x', page.height);
}}
onRenderSuccess={() => {
console.log('Page rendered successfully');
}}
/>
</Document>
);
}
// Multiple pages with different configurations
function MultiPageViewer() {
const [numPages, setNumPages] = useState(null);
return (
<Document
file="sample.pdf"
onLoadSuccess={({ numPages }) => setNumPages(numPages)}
>
{Array.from({ length: numPages }, (_, index) => (
<Page
key={`page_${index + 1}`}
pageNumber={index + 1}
scale={0.8}
renderTextLayer={false}
className="pdf-page"
/>
))}
</Document>
);
}Render Modes
Different rendering modes for various use cases and performance requirements.
type RenderMode = 'canvas' | 'custom' | 'none';
type CustomRenderer = React.FunctionComponent | React.ComponentClass;Usage Examples:
// Canvas mode (default) - renders to HTML5 canvas
<Page pageNumber={1} renderMode="canvas" />
// Custom renderer mode - use your own rendering component
function MyCustomRenderer() {
const pageContext = usePageContext();
// Custom rendering logic using page context
return <div>Custom rendered page</div>;
}
<Page
pageNumber={1}
renderMode="custom"
customRenderer={MyCustomRenderer}
/>
// None mode - no visual rendering, useful for text extraction
<Page pageNumber={1} renderMode="none" />Page Sizing and Scaling
Flexible sizing options with automatic scaling and fixed dimensions.
interface PageSizingProps {
/** Page scale factor (default: 1) */
scale?: number;
/** Fixed width in pixels */
width?: number;
/** Fixed height in pixels */
height?: number;
/** Page rotation in degrees */
rotate?: number | null;
/** Device pixel ratio for high DPI displays */
devicePixelRatio?: number;
}Usage Examples:
// Scale-based sizing
<Page pageNumber={1} scale={1.5} /> // 150% size
<Page pageNumber={1} scale={0.5} /> // 50% size
// Fixed width (height calculated automatically)
<Page pageNumber={1} width={800} />
// Fixed height (width calculated automatically)
<Page pageNumber={1} height={600} />
// Rotation
<Page pageNumber={1} rotate={90} /> // 90 degrees clockwise
<Page pageNumber={1} rotate={180} /> // upside down
<Page pageNumber={1} rotate={270} /> // 90 degrees counter-clockwise
// High DPI displays
<Page pageNumber={1} devicePixelRatio={2} />Text Layer
Text layer rendering for text selection, search, and accessibility.
interface TextLayerProps {
/** Whether to render text layer */
renderTextLayer?: boolean;
/** Custom text renderer function */
customTextRenderer?: CustomTextRenderer;
/** Function called when text content loads successfully */
onGetTextSuccess?: (textContent: TextContent) => void;
/** Function called when text content fails to load */
onGetTextError?: (error: Error) => void;
/** Function called when text layer renders successfully */
onRenderTextLayerSuccess?: () => void;
/** Function called when text layer fails to render */
onRenderTextLayerError?: (error: Error) => void;
}
type CustomTextRenderer = (
props: { pageIndex: number; pageNumber: number; itemIndex: number } & TextItem
) => string;
interface TextContent {
items: (TextItem | TextMarkedContent)[];
styles: Record<string, TextStyle>;
}
interface TextItem {
str: string;
dir: string;
width: number;
height: number;
transform: number[];
fontName: string;
}Usage Examples:
// Basic text layer
<Page pageNumber={1} renderTextLayer={true} />
// Custom text highlighting
function highlightSearchTerms(props) {
const { str } = props;
return str.replace(/search-term/gi, '<mark>$&</mark>');
}
<Page
pageNumber={1}
renderTextLayer={true}
customTextRenderer={highlightSearchTerms}
/>
// Text extraction
function TextExtractor() {
const [text, setText] = useState('');
return (
<Page
pageNumber={1}
renderMode="none"
onGetTextSuccess={(textContent) => {
const pageText = textContent.items
.filter(item => 'str' in item)
.map(item => item.str)
.join(' ');
setText(pageText);
}}
/>
);
}Annotation Layer
Annotation layer rendering for interactive links, forms, and other PDF annotations.
interface AnnotationLayerProps {
/** Whether to render annotation layer */
renderAnnotationLayer?: boolean;
/** Whether to render interactive forms */
renderForms?: boolean;
/** Function called when annotations load successfully */
onGetAnnotationsSuccess?: (annotations: Annotations) => void;
/** Function called when annotations fail to load */
onGetAnnotationsError?: (error: Error) => void;
/** Function called when annotation layer renders successfully */
onRenderAnnotationLayerSuccess?: () => void;
/** Function called when annotation layer fails to render */
onRenderAnnotationLayerError?: (error: unknown) => void;
}
type Annotations = AnnotationData[];
interface AnnotationData {
annotationType: number;
color?: number[];
dest?: Dest;
url?: string;
rect: number[];
subtype: string;
}Usage Examples:
// Basic annotations (links, etc.)
<Page
pageNumber={1}
renderAnnotationLayer={true}
/>
// Annotations with forms
<Page
pageNumber={1}
renderAnnotationLayer={true}
renderForms={true}
onGetAnnotationsSuccess={(annotations) => {
console.log('Found', annotations.length, 'annotations');
}}
/>
// Handle annotation clicks via Document
<Document
file="sample.pdf"
onItemClick={({ pageNumber, dest }) => {
console.log('Clicked annotation leading to page', pageNumber);
}}
>
<Page pageNumber={1} renderAnnotationLayer={true} />
</Document>Event Handlers
Comprehensive event system for page lifecycle and rendering states.
interface PageCallback extends PDFPageProxy {
/** Rendered page width in pixels */
width: number;
/** Rendered page height in pixels */
height: number;
/** Original page width from PDF */
originalWidth: number;
/** Original page height from PDF */
originalHeight: number;
}
type OnPageLoadSuccess = (page: PageCallback) => void;
type OnPageLoadError = (error: Error) => void;
type OnRenderSuccess = () => void;
type OnRenderError = (error: Error) => void;
type OnGetTextSuccess = (textContent: TextContent) => void;
type OnGetTextError = (error: Error) => void;
type OnGetAnnotationsSuccess = (annotations: Annotations) => void;
type OnGetAnnotationsError = (error: Error) => void;Page Context
Page context data available to child components and custom renderers.
interface PageRenderProps {
/** PDF page proxy object */
page: PDFPageProxy;
/** Zero-based page index */
pageIndex: number;
/** One-based page number */
pageNumber: number;
/** Page scale factor */
scale: number;
/** Page rotation in degrees */
rotate: number;
/** Canvas background color */
canvasBackground?: string;
/** Custom text renderer function */
customTextRenderer?: CustomTextRenderer;
/** Device pixel ratio */
devicePixelRatio?: number;
/** Whether forms should be rendered */
renderForms: boolean;
/** Whether text layer should be rendered */
renderTextLayer: boolean;
}Advanced Styling
Canvas customization and CSS styling options for page appearance.
interface PageStylingProps {
/** Canvas background color (any valid CSS color) */
canvasBackground?: string;
/** Class names for the page container */
className?: ClassName;
/** React ref for the page container div */
inputRef?: React.Ref<HTMLDivElement | null>;
/** React ref for the canvas element */
canvasRef?: React.Ref<HTMLCanvasElement>;
}Usage Examples:
// Custom canvas background
<Page
pageNumber={1}
canvasBackground="transparent"
/>
// CSS styling
<Page
pageNumber={1}
className="custom-page shadow-lg border-2"
style={{ margin: '20px' }}
/>
// Canvas reference for custom operations
function CanvasEditor() {
const canvasRef = useRef(null);
const addWatermark = () => {
const canvas = canvasRef.current;
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'rgba(255, 0, 0, 0.3)';
ctx.fillText('CONFIDENTIAL', 50, 50);
};
return (
<Page
pageNumber={1}
canvasRef={canvasRef}
onRenderSuccess={addWatermark}
/>
);
}Install with Tessl CLI
npx tessl i tessl/npm-react-pdf