react-ipdf-viewer-lite

react-ipdf-viewer-lite

A React component for viewing PDF documents using Mozilla's pdf.js. Embed a customizable PDF viewer in your React applications with page zoom, theme, Full Screen, Page Count and download support.

Demo

Explore a live demo of react-ipdf-viewer-lite in action:

• Live Demo

See the PDF viewer with zoom, navigation, and theme support directly in your browser.

Features

• Render PDFs from URLs or local files with smooth navigation.
• Enable zoom download and full-screen via toolbar.
• Support light and dark themes for accessibility.
• Compatible with modern browsers (Chrome, Firefox, Safari, Edge).
• Built-in zoom and navigation controls.
• TypeScript-compatible for type-safe development.

Installation

Install the package via npm:

npm install react-ipdf-viewer-lite

Or using Yarn:

yarn add react-ipdf-viewer-lite

Dependencies

Ensure you have the following peer dependencies installed:

• react (>=16.8.0)
• react-dom (>=16.8.0)
• pdfjs-dist (>=2.9.359)

Install them if needed:

npm install react react-dom pdfjs-dist

Usage

Import the ReactIPdfViewerLite component and provide a PDF file URL or path via the src prop. The component supports PDF documents only; place local PDFs in your public/ folder or use a hosted URL.

Example: Viewing a PDF

import React from "react";
import { ReactIPdfViewerLite } from "react-ipdf-viewer-lite";
import "./App.css";

const PDF = "sample.pdf";

const App = () => {
  return (
    <div className="App">
      <ReactIPdfViewerLite src={PDF} theme='light'/>
    </div>
  );
};

export default App;

API

ReactIPdfViewerLite

A React component to render a PDF viewer with customizable controls.

Props

Prop	Type	Description	Default	Example
src	string	URL or path to the PDF file to render. Also accepts document={{ url }}.	None	'sample.pdf' or 'https://example.com/sample.pdf'
theme	string	Sets the viewer’s theme. Options: 'light', 'dark'.	'dark'	'light'

Error Handling and Troubleshooting

The ReactIPdfViewerLite component may encounter issues when loading or rendering PDFs. Below are common errors and solutions.

Common Errors

• Invalid PDF URL

  • Error: "Failed to load PDF file" or "Invalid PDF format".
  • Cause: The src prop points to an invalid or inaccessible URL.
  • Solution: Verify the URL is correct and accessible. Use a local file in public/ or a hosted HTTPS URL.
  • Example:

    <ReactIPdfViewer src="/sample.pdf" />
    

• CORS Restrictions

  • Error: "Cross-Origin Request Blocked" when loading an external PDF.
  • Cause: The PDF’s server doesn’t allow cross-origin requests.
  • Solution: Host the PDF on the same domain or use a CORS proxy. Alternatively, serve from public/.
  • Example:

    const App = () => {
      const pdfUrl =
        process.env.NODE_ENV === "development"
          ? "/sample.pdf"
          : "https://your-domain.com/sample.pdf";
      return <ReactIPdfViewerLite src={pdfUrl} />;
    };
    

• Content Security Policy (CSP) Error

  • Error: "Refused to connect to 'blob:...' because it violates the Content Security Policy".
  • Cause: Blob URLs used by pdf.js are blocked by your app’s CSP.
  • Solution: Update your CSP to allow blob URLs in the connect-src directive.

    <meta
      http-equiv="Content-Security-Policy"
      content="connect-src 'self' blob:;"
    />
    

• Mobile Rendering Issues

  • Error: PDF fails to render on mobile devices, or blob URLs are blocked.
  • Cause: Browser security restricts blob URLs or iframe rendering on mobile.
  • Solution: Use direct HTTPS URLs and rely on pdf.js canvas rendering. Test with a local PDF.
  • Example:

    <ReactIPdfViewerLite src="/sample.pdf" autoHeight />
    

• File Loading Failure

  • Error: "PDF.js: Failed to fetch" or "Corrupted PDF".

  • Cause: The PDF file is corrupted or unsupported by pdf.js.

  • Solution: Validate the PDF with Adobe Acrobat. Use a try-catch block for error handling.

  • Example:

    import React, { useState } from "react";
    import {ReactIPdfViewerLite} from "react-ipdf-viewer-lite";
    
    const App = () => {
      const [error, setError] = useState(null);
      const handleError = (err) => setError(err.message);
    
      return (
        <div>
          {error ? <p>Error: {error}</p> : null}
          <ReactIPdfViewerLite
            src="sample.pdf"
          />
        </div>
      );
    };
    

Error Handling Tips

• Validate Props: Ensure src is a valid string. Use a fallback URL if needed.

  const pdfUrl = src || "/fallback.pdf";
  <ReactIPdfViewer src={pdfUrl} />;
  

• Handle Load Events: Use onError (if supported) or wrap in try-catch.
• Test on Mobile: Verify rendering on iOS/Android.
• Monitor Console: Check for pdf.js warnings (e.g., missing CMaps).
• Use HTTPS: Serve PDFs over HTTPS to avoid mixed content errors.

Additional Features

Beyond the core props, ReactIPdfViewerLite offers:

• Zoom Controls: Adjust zoom via toolbar buttons.
• TypeScript Compatibility: Works in TypeScript projects.

Limitations

• Supports PDFs only.
• No built-in annotations or text selection.
• Large PDFs may impact performance on low-end devices.

Contributing

Contributions are welcome! To contribute:

• Fork the repository.
• Create a feature branch (git checkout -b feature/YourFeature).
• Commit your changes (git commit -m 'Add YourFeature').
• Push to the branch (git push origin feature/YourFeature).
• Open a Pull Request.

Please ensure your code follows the existing style and includes tests where applicable.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For issues, questions, or feature requests, please open an issue on the GitHub repository or contact Sudeepa R.# react-ipdf-viewer