@cyntler/react-doc-viewer

File viewer for React v17+.

This is a fork of https://github.com/Alcumus/react-doc-viewer (inactivity for a long time).

Important note!

[!WARNING] This library uses the official MS Office online document viewing service. This means it works on an iframe basis and only supports public file URLs! Therefore, it may not be compatible with all projects. Currently, there is no way to natively render MS Office documents in the browser.

Table of Contents

• Supported file types
• Storybook Demo
• Installation
• Usage
  • Required styles
  • Basic
  • Initial Active Document
  • Control over the displayed document
  • Displaying blob/uploaded documents
  • Included Renderers
  • Custom Renderer
  • Custom File Loader
• Theme
• Custom pre-fetch HTTP Verb
• Custom Request Headers
• Internationalization (i18n)
• Styling
  • CSS Class
  • CSS Class Default Override
  • React Inline
  • Styled Components
• Using DocViewerRef
• Config
  • Overriding Header Component
  • Overriding Loading Renderer
  • Overriding No Renderer (Error)

Supported file types

Extension	MIME Type	Comments
bmp	image/bmp
csv	text/csv
odt	application/vnd.oasis.opendocument.text
doc	application/msword	Public URLs only!
docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document	Public URLs only!
gif	image/gif
htm	text/htm
html	text/html
jpg	image/jpg
jpeg	image/jpeg
pdf	application/pdf
png	image/png
ppt	application/vnd.ms-powerpoint	Public URLs only!
pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation	Public URLs only!
tiff	image/tiff
txt	text/plain
xls	application/vnd.ms-excel	Public URLs only!
xlsx	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	Public URLs only!
mp4	video/mp4
webp	image/webp

Storybook Demo

https://cyntler.github.io/react-doc-viewer

Installation

Use one of the package managers for Node.js.

1 npm i @cyntler/react-doc-viewer
2 # or
3 yarn add @cyntler/react-doc-viewer

Usage

Warning: By default the component height will expand and contract to the current loaded file. The width will expand to fill the parent.

Required styles

The library exports a CSS file containing classes needed for correct rendering of e.g. PDF files. It is best to include it at the beginning of the application or in the place where you use this library.

1import "@cyntler/react-doc-viewer/dist/index.css";

Basic

DocViewer requires at least an array of document objects to function. Each document object must have a uri to a file, either a url that returns a file or a local file.

1import DocViewer, { DocViewerRenderers } from "@cyntler/react-doc-viewer";
2import "@cyntler/react-doc-viewer/dist/index.css";
3
4function App() {
5  const docs = [
6    { uri: "https://url-to-my-pdf.pdf" }, // Remote file
7    { uri: require("./example-files/pdf.pdf") }, // Local File
8  ];
9
10  return <DocViewer documents={docs} pluginRenderers={DocViewerRenderers} />;
11}

Initial Active Document

By default, the first item in your documents array will be displayed after the component is rendered. However, there is a prop initialActiveDocument that you can point to the initial document that should be displayed.

1import DocViewer, { DocViewerRenderers } from "@cyntler/react-doc-viewer";
2import "@cyntler/react-doc-viewer/dist/index.css";
3
4const App = () => {
5  const docs = [
6    { uri: "https://url-to-my-pdf.pdf" }, // Remote file
7    { uri: require("./example-files/pdf.pdf") }, // Local File
8  ];
9
10  return (
11    <DocViewer
12      documents={docs}
13      initialActiveDocument={docs[1]}
14      pluginRenderers={DocViewerRenderers}
15    />
16  );
17};

Control over the displayed document

From version 1.11.0 you can control the displayed document through two props: activeDocument and onDocumentChange.

1const DocViewerControlOverDisplayedDocument = () => {
2  const docs = [
3    { uri: "https://url-to-my-pdf.pdf" }, // Remote file
4    { uri: require("./example-files/pdf.pdf") }, // Local File
5  ];
6  const [activeDocument, setActiveDocument] = useState(docs[0]);
7
8  const handleDocumentChange = (document) => {
9    setActiveDocument(document);
10  };
11
12  return (
13    <>
14      <DocViewer
15        documents={docs}
16        activeDocument={activeDocument}
17        onDocumentChange={handleDocumentChange}
18      />
19    </>
20  );
21};

Displaying blob/uploaded documents

Since v1.6.2 you can use documents in the form of blobs, which allows you to e.g. display uploaded files.

1const DocViewerWithInputApp = () => {
2  const [selectedDocs, setSelectedDocs] = useState<File[]>([]);
3
4  return (
5    <>
6      <input
7        type="file"
8        accept=".pdf"
9        multiple
10        onChange={(el) =>
11          el.target.files?.length &&
12          setSelectedDocs(Array.from(el.target.files))
13        }
14      />
15      <DocViewer
16        documents={selectedDocs.map((file) => ({
17          uri: window.URL.createObjectURL(file),
18          fileName: file.name,
19        }))}
20        pluginRenderers={DocViewerRenderers}
21      />
22    </>
23  );
24};

Included Renderers

To use the included renderers. DocViewerRenderers is an Array of all the included renderers.

1import DocViewer, { DocViewerRenderers } from "@cyntler/react-doc-viewer";
2import "@cyntler/react-doc-viewer/dist/index.css";
3
4<DocViewer
5  pluginRenderers={DocViewerRenderers}
6  {/* ... */}
7/>;

Or you can import individual renderers.

1import DocViewer, { PDFRenderer, PNGRenderer } from "@cyntler/react-doc-viewer";
2import "@cyntler/react-doc-viewer/dist/index.css";
3
4<DocViewer
5  pluginRenderers={[PDFRenderer, PNGRenderer]}
6  {/* ... */}
7/>;

Custom Renderer

To create a custom renderer, that will just exist for your project.

1import React from "react";
2import DocViewer from "@cyntler/react-doc-viewer";
3
4const MyCustomPNGRenderer: DocRenderer = ({
5  mainState: { currentDocument },
6}) => {
7  if (!currentDocument) return null;
8
9  return (
10    <div id="my-png-renderer">
11      <img id="png-img" src={currentDocument.fileData as string} />
12    </div>
13  );
14};
15
16MyCustomPNGRenderer.fileTypes = ["png", "image/png"];
17MyCustomPNGRenderer.weight = 1;

And supply it to pluginRenderers inside an Array.

1import DocViewer, { DocViewerRenderers } from "@cyntler/react-doc-viewer";
2import "@cyntler/react-doc-viewer/dist/index.css";
3
4<DocViewer
5  pluginRenderers={[MyCustomPNGRenderer]}
6  documents={
7    [
8      // ...
9    ]
10  }
11/>;

Custom File Loader

If you need to prevent the actual loading of the file by @cyntler/react-doc-viewer.
You can decorate your custom renderer with a callback to do as you wish. e.g. Load the file yourself in an iFrame.

1MyCustomPNGRenderer.fileLoader = ({
2  documentURI,
3  signal,
4  fileLoaderComplete,
5}) => {
6  myCustomFileLoaderCode().then(() => {
7    // Whenever you have finished you must call fileLoaderComplete() to remove the loading animation
8    fileLoaderComplete();
9  });
10};

Theme

You can provide a theme object with one or all of the available properties.

1<DocViewer
2  documents={docs}
3  theme={{
4    primary: "#5296d8",
5    secondary: "#ffffff",
6    tertiary: "#5296d899",
7    textPrimary: "#ffffff",
8    textSecondary: "#5296d8",
9    textTertiary: "#00000099",
10    disableThemeScrollbar: false,
11  }}
12/>

Custom pre-fetch HTTP Verb

Some services (such as AWS) provide URLs that works only for one pre-configured verb. By default, @cyntler/react-doc-viewer fetches document metadata through a HEAD request in order to guess its Content-Type. If you need to have a specific verb for the pre-fetching, use the prefetchMethod option on the DocViewer:

1import DocViewer, { DocViewerRenderers } from "@cyntler/react-doc-viewer";
2
3<DocViewer prefetchMethod="GET" />;

Custom Request Headers

Provide request headers, i.e. for authenticating with an API etc.

1const headers = {
2  "X-Access-Token": "1234567890",
3  "My-Custom-Header": "my-custom-value",
4};
5
6<DocViewer documents={docs} prefetchMethod="GET" requestHeaders={headers} />;

Internationalization (i18n)

From v1.6.0 you can pass the language prop to the DocViewer component to get translated sentences and words that can be displayed by this library.

1<DocViewer documents={docs} language="pl" />

The translations are based on the .json files that can be found in the src/locales directory.

Styling

Any styling applied to the <DocViewer> component, is directly applied to the main div container.

CSS Class

1<DocViewer documents={docs} className="my-doc-viewer-style" />

CSS Class Default Override

Each component / div already has a DOM id that can be used to style any part of the document viewer.

1#react-doc-viewer #header-bar {
2  background-color: #faf;
3}

React Inline

1<DocViewer documents={docs} style={{ width: 500, height: 500 }} />

Styled Components

1import styled from "styled-components";
2
3// ...
4
5<MyDocViewer documents={docs} />;
6
7// ...
8
9const MyDocViewer = styled(DocViewer)`
10  border-radius: 10px;
11`;

Using DocViewerRef

Since v1.13.0 you can control the display of the document with reference.

1import DocViewer, { DocViewerRef } from "@cyntler/react-doc-viewer";
2
3export const UsingRef = () => {
4  const docViewerRef = useRef<DocViewerRef>(null);
5
6  return (
7    <>
8      <div>
9        <button onClick={() => docViewerRef?.current?.prev()}>
10          Prev Document By Ref
11        </button>
12        <button onClick={() => docViewerRef?.current?.next()}>
13          Next Document By Ref
14        </button>
15      </div>
16      <DocViewer
17        ref={docViewerRef}
18        documents={docs}
19        config={{ header: { disableHeader: true } }}
20      />
21    </>
22  );
23};

Config

You can provide a config object, which configures parts of the component as required.

1<DocViewer
2  documents={docs}
3  config={{
4    header: {
5      disableHeader: false,
6      disableFileName: false,
7      retainURLParams: false,
8    },
9    csvDelimiter: ",", // "," as default,
10    pdfZoom: {
11      defaultZoom: 1.1, // 1 as default,
12      zoomJump: 0.2, // 0.1 as default,
13    },
14    pdfVerticalScrollByDefault: true, // false as default
15  }}
16/>

Overriding Header Component

You can pass a callback function to config.header.overrideComponent that returns a React Element. The function's parameters will be populated and usable, this function will also be re-called whenever the mainState updates. Parameters include the state object from the main component, and document navigation functions for previousDocument and nextDocument.

Example:

1const MyHeader: IHeaderOverride = (state, previousDocument, nextDocument) => {
2  if (!state.currentDocument || state.config?.header?.disableFileName) {
3    return null;
4  }
5
6  return (
7    <>
8      <div>{state.currentDocument.uri || ""}</div>
9      <div>
10        <button onClick={previousDocument} disabled={state.currentFileNo === 0}>
11          Previous Document
12        </button>
13        <button
14          onClick={nextDocument}
15          disabled={state.currentFileNo >= state.documents.length - 1}
16        >
17          Next Document
18        </button>
19      </div>
20    </>
21  );
22};
23
24<DocViewer
25  pluginRenderers={DocViewerRenderers}
26  documents={
27    {
28      // ...
29    }
30  }
31  config={{
32    header: {
33      overrideComponent: MyHeader,
34    },
35  }}
36/>;

Overriding Loading Renderer

You can pass a callback function to config.loadingRenderer.overrideComponent that returns a React Element.

Example:

1const MyLoadingRenderer = ({ document, fileName }) => {
2  const fileText = fileName || document?.fileType || "";
3
4  if (fileText) {
5    return <div>Loading Renderer ({fileText})...</div>;
6  }
7
8  return <div>Loading Renderer...</div>;
9};
10
11<DocViewer
12  pluginRenderers={DocViewerRenderers}
13  documents={
14    {
15      // ...
16    }
17  }
18  config={{
19    loadingRenderer: {
20      overrideComponent: MyLoadingRenderer,
21    },
22  }}
23/>;

By default, the loading component is rendered if document loading process takes more than 500 ms.

You can change this time value or disable this feature to make the component display immediately:

1const MyLoadingRenderer = ({ document, fileName }) => {
2  ...
3};
4
5<DocViewer
6  pluginRenderers={DocViewerRenderers}
7  documents={
8    {
9      // ...
10    }
11  }
12  config={{
13    loadingRenderer: {
14      overrideComponent: MyLoadingRenderer,
15      showLoadingTimeout: false, // false if you want to disable or number to provide your own value (ms)
16    },
17  }}
18/>;

Overriding No Renderer (Error)

You can pass a callback function to config.noRenderer.overrideComponent that returns a React Element.

Example:

1const MyNoRenderer = ({ document, fileName }) => {
2  const fileText = fileName || document?.fileType || "";
3
4  if (fileText) {
5    return <div>No Renderer Error! ({fileText})</div>;
6  }
7
8  return <div>No Renderer Error!</div>;
9};
10
11<DocViewer
12  pluginRenderers={DocViewerRenderers}
13  documents={
14    {
15      // ...
16    }
17  }
18  config={{
19    noRenderer: {
20      overrideComponent: MyNoRenderer,
21    },
22  }}
23/>;