Updates

New features

• The plugin exposes new functions:

• The `Viewer` component adds a new property to disable smooth scroll:

<Viewer enableSmoothScroll={false} />

• It's possible to set the range of pages that will be pre-rendered. The range consists of the visible pages and some pages before and after the visible pages.

import type { SetRenderRange, VisiblePagesRange } from '@react-pdf-viewer/core';

const setRenderRange: SetRenderRange = React.useCallback((visiblePagesRange: VisiblePagesRange) => {
    return {
        startPage: visiblePagesRange.startPage - 10,
        endPage: visiblePagesRange.endPage + 10,
    };
}, []);

// Another usage: render the first 20 pages initially
const setRenderRange: SetRenderRange = React.useCallback((visiblePagesRange: VisiblePagesRange) => {
    return {
        startPage: visiblePagesRange.endPage <= 20 ? 0 : visiblePagesRange.startPage - 5,
        endPage:
            visiblePagesRange.startPage <= 20
                ? Math.max(20, visiblePagesRange.endPage + 5)
                : visiblePagesRange.endPage + 5,
    };
}, []);

<Viewer setRenderRange={setRenderRange} />;

• The `Cover` component adds new `width` property:

const { Cover } = thumbnailPluginInstance;

// Render the cover of second page
<Cover getPageIndex={() => 1} width={300} />;

Improvements

• Custom elements added to the page layer can be positioned outside of the page
• Improve the performance by removing many unnecessary rerenders. They are triggered when smooth scrolling or entering the full-screen mode
• Uses can zoom by pinching a trackpad
• The page navigation plugin adds more shortcuts:

Bug fixes

• The `Viewer` component scrolls to the `initialPage` page automatically after resizing the container or browser
• The viewer doesn't keep the current page when entering the full-screen mode in some cases

Breaking change

• The `jumpToDestination` function now has only a single property. You don't have to change anything if your application doesn't have any custom plugin using the `jumpToDestination` function.

// Before
import type { DestinationOffsetFromViewport } from '@react-pdf-viewer/core';
import { SpecialZoomLevel } from '@react-pdf-viewer/core';

jumpToDestination(
    pageIndex: number,
    bottomOffset: number | DestinationOffsetFromViewport,
    leftOffset: number | DestinationOffsetFromViewport,
    scaleTo?: number | SpecialZoomLevel
);

// After
import type { Destination } from '@react-pdf-viewer/core';

jumpToDestination(destination: Destination);

New features

• Add `pagesContainerRef` to `RenderViewer`, so the plugin can access the pages container more easily
• The `Viewer` component adds new property to customize the view of a protected document:

import { RenderProtectedViewProps, Viewer } from '@react-pdf-viewer/core';

const ProtectedView: React.FC<RenderProtectedViewProps> = ({ passwordStatus, verifyPassword }) => {
    ...
};

<Viewer renderProtectedView={renderProps => <ProtectedView {...renderProps} />} />

• The page navigation plugin exposes functions to jump to the previous and next pages

import { pageNavigationPlugin } from '@react-pdf-viewer/page-navigation';

const pageNavigationPluginInstance = pageNavigationPlugin();
const { jumpToNextPage, jumpToPreviousPage } = pageNavigationPluginInstance;

• The `Thumbnails` component provides new property to display the thumbnails in the given direction:

import { ThumbnailDirection } from '@react-pdf-viewer/thumbnail';

// Display thumbnails horizontally
<Thumbnails thumbnailDirection={ThumbnailDirection.Horizontal} />

// Display thumbnails vertically
<Thumbnails thumbnailDirection={ThumbnailDirection.Vertical} />

Improvements

• Change the shortcuts to behave identically as other applications (such as Adobe Acrobat):

• Support pdf-js 3.2.146
• The thumbnails are updated to look identically to the pages when users change the viewmode

Bug fixes

• The dual page viewmode doesn't work well with the initial page (`initialPage`) option
• Page navigation doesn't move to the final page properly

Breaking change

• The PageLayout's `tranformSize` property is changed to `transformSize`

New features

• New page scrolling mode:

import { ScrollMode, Viewer } from '@react-pdf-viewer/core';

<Viewer scrollMode={ScrollMode.Page} />;

• New three page viewmodes:

import { ViewMode, Viewer } from '@react-pdf-viewer/core';

<Viewer viewMode={ViewMode.DualPage} />;

• `PluginFunctions` provides new `jumpToPreviousPage` and `jumpToNextPage` to jump to the previous and next pages
• The scroll mode plugin provides new `DualPageCoverViewModeIcon`, `DualPageViewModeIcon` and `PageScrollingIcon` icons

Bug fixes

• Jumping to the previous and next pages in wrapped scrol mode don't work properly
• Zooming doesn't keep current position properly

New feature

• New `pageLayout` option to customize the layout of each page. The following code adds margin between pages, and center the page in its container:

import { type PageLayout, Viewer } from '@react-pdf-viewer/core';

const pageLayout: PageLayout = {
    buildPageStyles: () => ({
        alignItems: 'center',
        display: 'flex',
        justifyContent: 'center',
    }),
    tranformSize: ({ size }) => ({ height: size.height + 30, width: size.width + 30 }),
};

<Viewer pageLayout={pageLayout} />;

Bug fixes

• Keep the current page after rotating the document

• Clicking a link annotation doesn't go to the correct destination position
• Don't scroll to the top of the target page corresponding to the `initialPage` option

Breaking change

• The `pageHeight` and `pageWidth` properties in `RenderViewer` are replaced with the `pageSizes` property that are the sizes of pages. You don't have to do anything if you don't develope your own plugin using those properties.

New features

• Set the initial rotation with the new `initialRotation` parameter:

<Viewer initialRotation={90} />

• The highlight plugin provides new function to switch the trigger mode:

const highlightPluginInstance = highlightPlugin();
const { switchTrigger } = highlightPluginInstance;

// Switch to None
switchTrigger(Trigger.None);

// Switch to Selection mode
switchTrigger(Trigger.TextSelection);

• Users can click and drag to highlight an area

Improvements

• Adjust the pointer when hovering the mouse over checkboxes inside the search popover
• Keep the expanded/collapsed state of each bookmark
• Set the `title` and `aria-label` attributes for link annotations without using the Bookmark plugin
• Support pdf-js 3.0.279
• The `RenderBookmarkItemProps` props includes new `path` property that indicates the path from each bookmark item to the root
• `SelectionData` provides more information about the selected text including:

• The open file dialog filters PDF files by default
• The search popover should perform search based on the initial keyword passed to the `keyword` option:

const searchPluginInstance = searchPlugin({
    keyword: '...',
});

• `RenderSearchProps` adds new `isDocumentLoaded` property that indicates if the document is loaded. You can use it to perform searching for a keyword in a sidebar:

import type { Match, RenderSearchProps } from '@react-pdf-viewer/search';

const SearchSidebarInner: React.FC<{
    renderSearchProps: RenderSearchProps
}> = ({ renderSearchProps }) => {
    const [matches, setMatches] = React.useState<Match[]>([]);
    const { isDocumentLoaded, keyword, search } = renderSearchProps;

    React.useEffect(() => {
        if (isDocumentLoaded && keyword) {
            search().then((matches) => {
                setMatches(matches);
            });
        }
    }, [isDocumentLoaded]);

    return (
        // Display matches ...
    );
};

Bug fixes

• Can't render certain PDF documents that contain an annotation whose destination consists of non alphabetical characters
• Popover doesn't work if the `Viewer` is rendered inside ShadowDOM
• Replace the deprecated `contents` and `title` properties of annotations with corresponding objects
• The annotation link doesn't navigate to the correct page in some cases
• The `Cover` component doesn't rotate the corresponding rotated page
• The `jumpToHighlightArea` function does not work properly with some documents
• The `startPageIndex` and `endPageIndex` properties of `SelectionData` aren't correct

Breaking change

• In addition to selecting texts, users can click and drag to highlight a particular area. The second way doesn't provide the `SelectionData` data. The `SelectionData` property in `RenderHighlightContentProps` and `RenderHighlightTargetProps` turn to optional properties.

interface RenderHighlightContentProps {
    selectionData?: SelectionData;
}

interface RenderHighlightTargetProps {
    selectionData?: SelectionData;
}

if (renderHighlightContentProps.selectionData) {
    // Do something ...
}

if (renderHighlightTargetProps.selectionData) {
    // Do something ...
}

New features

• You can customize the bookmarks by using the `renderBookmarkItem` properly:

<Bookmark renderBookmarkItem={renderBookmarkItem} />

• The default layout plugin provides new `toggleTab` function to toggle a given tab in the sidebar:

const defaultLayoutPluginInstance = defaultLayoutPlugin();
const { toggleTab } = defaultLayoutPluginInstance;

// Toggle the second tab
toggleTab(1);

Improvement

• Clicking `Command` + `ArrowUp` (on macOS) or `Ctrl` + `ArrowUp` (on Windows) will bring users to the previous clicked link annotation. You can disable that shortcuts via the `enableShortcuts` option:

// Use the standalone page navigation plugin
const pageNavigationPluginInstance = pageNavigationPlugin({
    enableShortcuts: false,
});

// Use the default layout plugin
const defaultLayoutPluginInstance = defaultLayoutPlugin({
    toolbarPlugin: {
        pageNavigationPlugin: {
            enableShortcuts: false,
        },
    },
});

Bug fixes

• Clicking a particular bookmark might not go to the destination
• Targets of link annotations are sanitized to avoid secutiry issues
• The `CharacterMap` type isn't available
• The `onPageChange` callback does not trigger if the current page equals to the initial page
• The page navigation options are missing when creating a toolbar plugin
• The search popover always shows up after pressing shortcuts
• The viewer always navigates to previous, next pages after users press shortcuts even the document isn't focused

New features

• Allow to choose pages when printing a document via the `setPages` option. It is a function that takes the current document and returns the list of zero-based indexes of pages you want to print.

import type { PdfJs } from '@react-pdf-viewer/core';
import { printPlugin } from '@react-pdf-viewer/print';

const printPluginInstance = printPlugin({
    setPages: (doc: PdfJs.PdfDocument) => number[],
});

// Only print the even pages
const printPluginInstance = printPlugin({
    setPages: (doc) =>
        Array(doc.numPages)
            .fill(0)
            .map((_, i) => i)
            .filter((i) => (i + 1) % 2 === 0),
});

// Only print the odd pages
const printPluginInstance = printPlugin({
    setPages: (doc) =>
        Array(doc.numPages)
            .fill(0)
            .map((_, i) => i)
            .filter((i) => (i + 1) % 2 === 1),
});

const defaultLayoutPluginInstance = defaultLayoutPlugin({
    toolbarPlugin: {
        printPlugin: {
            setPages: ...,
        },
    },
});

import {
    getAllPagesNumbers,
    getCustomPagesNumbers,
    getEvenPagesNumbers,
    getOddPagesNumbers,
} from '@react-pdf-viewer/print';

const printPluginInstance = printPlugin({
    setPages: getEvenPagesNumbers,
});

• The target print pages can be determined from users' input:

import { getEvenPagesNumbers } from '@react-pdf-viewer/print';
const printPluginInstance = printPlugin();

const { setPages } = printPluginInstance;

// Show UI for users to choose pages
const handleChooseEvenPages = () => setPages(getEvenPagesNumbers);

<label>
    <input type="radio" onChange={handleChooseEvenPages} /> Print even pages
</label>;

• The print plugin exposes the `print` function:

import { printPlugin } from '@react-pdf-viewer/print';

const printPluginInstance = printPlugin();
const { print } = printPluginInstance;

import { defaultLayoutPlugin } from '@react-pdf-viewer/default-layout';

const defaultLayoutPluginInstance = defaultLayoutPlugin();
const { print } = defaultLayoutPluginInstance.toolbarPluginInstance.printPluginInstance;

• You can customize the progress bar when preparing pages to print:

const printPluginInstance = printPlugin({
    renderProgressBar: (numLoadedPages: number, numPages: number, onCancel: () => void) => (
        // Render the progress bar
    ),
});

Improvement

• Replace the icons used in buttons to download and open a document with less confusing one

import { DownloadIcon } from '@react-pdf-viewer/get-file';
import { OpenFileIcon } from '@react-pdf-viewer/open';

Bug fix

• Can't search or set the initial keyword for scanned documents

New feature

• Be able to customize the highlighted elements when searching for a keyword:

const searchPluginInstance = searchPlugin({
    renderHighlights: (renderProps: RenderHighlightsProps) => (
        // Your custom highlighted elements
    ),
});

Improvements

• The highlight plugin supports double click. Users can double click to select the entire text of a given element
• The page navigation plugin allows to jump to the previous and next pages with shortcuts.

// Use the standalone page navigation plugin
const pageNavigationPluginInstance = pageNavigationPlugin({
    enableShortcuts: false,
});

// Use the default layout plugin
const defaultLayoutPluginInstance = defaultLayoutPlugin({
    toolbarPlugin: {
        pageNavigationPlugin: {
            enableShortcuts: false,
        },
    },
});

Bug fixes

• Don't highlight the entire page when selecting multiple lines
• The default layout plugin throws an exception if the `setInitialTabFromPageMode` function returns a `Promise` which resolves an invalid tab index
• The highlight plugin throws an exception when double click a page without selecting any text
• The search plugin can't set the initial keyword when using with the highlight plugin

New feature

• It's possible to set the initial tab in the default layout:

import { defaultLayoutPlugin } from '@react-pdf-viewer/default-layout';

const defaultLayoutPluginInstance = defaultLayoutPlugin({
    // The `Bookmark` tab is active initially
    setInitialTab: () => Promise.resolve(1),
});

import { defaultLayoutPlugin, setInitialTabFromPageMode } from '@react-pdf-viewer/default-layout';

const defaultLayoutPluginInstance = defaultLayoutPlugin({
    setInitialTab: setInitialTabFromPageMode,
});

Improvement

• Navigate to the previous and next pages
• Jump to a given page
• Click a thumbnail to go to a particular page
• Click a bookmark to go to a particular destination
• Jump between search results
• Jump to a given highlighted text

Bug fixes

• Can't add highlight to selected text
• Keep current position after zooming

Improvements

• Clicking `Enter` automatically jumps to the next match when being focused on the keyword field
• Support documents which are optimized for web. Users don't have to wait the full document loaded to see the first page.

Bug fixes

• Automatically scroll to the thumbnail of the initial page when it's set
• The text might not be selectable if a plugin registers the `renderPageLayer` method
• There is a page that is not rendered even it is visible when users zoom the document

Bug fixes

• The `initialPage` option doesn't work
• The pages are flickering when zooming the document
• There is a page that is not rendered even it is visible when users zoom the document continuously

New feature

• The thumbnail plugin adds new option for customizing the width of thumbnails:

const thumbnailPluginInstance = thumbnailPlugin({
    thumbnailWidth: 150,
});

// Use with the default layout plugin
const defaultLayoutPluginInstance = defaultLayoutPlugin({
    thumbnailPlugin: {
        thumbnailWidth: 150,
    },
});

Bug fix

• Support React 18 strict mode

<React.StrictMode>
    <Worker workerUrl="...">
        <Viewer fileUrl="..." />
    </Worker>
</React.StrictMode>

New features

• The `Bookmarks` component provides new property that can be used to set a bookmark expanded or collapsed initially. This example expands bookmarks whose depth are zero:

const setBookmarkExpanded = ({ bookmark, depth, doc, index }) => {
    // `bookmark` is the bookmark data structure
    // `depth` is the current depth
    // `doc` is the current document
    // `index` is the zero-based index of bookmark relative to its parent
    return depth === 0;
};

<Bookmarks isBookmarkExpanded={setBookmarkExpanded} />;

// Expand bookmarks initially
const setBookmarkExpanded = ({ bookmark, depth, doc, index }) => true;

// Collapse bookmarks initially
const setBookmarkExpanded = ({ bookmark, depth, doc, index }) => false;

• The Page Navigation plugin provides new `NumberOfPages` component that displays the total number of pages

Improvements

• Align bookmark titles
• Compatible with React 18
• In previous versions, all bookmarks were expanded by default. From this version, a bookmark will be shown or hidden initially depending on its data structure. You can see this behaviour on popular viewers such as Acrobat Reader.
• The toolbar slot `NumberOfPages` provides the ability of customizing the number of pages

Bug fixes

• The hightlights are lost when the whole words option is enabled
• There is a visible page that isn't rendered when setting the zoom level as page width

New features

• The `Popover` component has new prop `lockScroll` which indicates whether the `body` element is scrollable or not. By default, it takes the `true` value
• The `Viewer` component adds new `onRotate` callback that is invoked when users rotate the document:

<Viewer
    onRotate={({ direction, doc, rotation }) => {
        // `direction` is the rotate direction
        // `doc` is the current document
        // `rotation` is the latest rotation value
    }}
/>

• Provide the ability of rotating a particular page. You can customize a thumbnail renderer to add the rotating functionality to each page:

const renderThumbnailItem = (props: RenderThumbnailItemProps) => (
    <MinimalButton onClick={() => props.onRotatePage(RotateDirection.Forward)}>
        <RotateForwardIcon />
    </MinimalButton>
    <MinimalButton onClick={() => props.onRotatePage(RotateDirection.Backward)}>
        <RotateBackwardIcon />
    </MinimalButton>
);

const thumbnailPluginInstance = thumbnailPlugin();
const { Thumbnails } = thumbnailPluginInstance;

<Thumbnails renderThumbnailItem={renderThumbnailItem} />

const renderPage: RenderPage = (props: RenderPageProps) => (
    <>
        {props.canvasLayer.children}
        <div>
            <MinimalButton onClick={() => props.onRotatePage(RotateDirection.Forward)}>
                <RotateForwardIcon />
            </MinimalButton>
            <MinimalButton onClick={() => props.onRotatePage(RotateDirection.Backward)}>
                <RotateBackwardIcon />
            </MinimalButton>
        </div>
        {props.annotationLayer.children}
        {props.textLayer.children}
    </>
);

<Viewer renderPage={renderPage} />;

const rotatePluginInstance = rotatePlugin();
const { RotatePage } = rotatePluginInstance;

<RotatePage>
    {(props) => <PrimaryButton onClick={() => props.onRotatePage(0, RotateDirection.Forward)}>Rotate the first page forward</PrimaryButton>}
</RotatePage>
<RotatePage>
    {(props) => <PrimaryButton onClick={() => props.onRotatePage(0, RotateDirection.Backward)}>Rotate the first page backward</PrimaryButton>}
</RotatePage>

• The `onRotatePage` event is triggered when a page is rotated:

<Viewer
    onRotatePage={({ direction, doc, pageIndex, rotation }) => {
        // `direction` is the rotate direction
        // `doc` is the current document
        // `pageIndex` is the zero-based page index
        // `rotation` is the latest rotation value
    }}
/>

Improvements

• The search popover is opened if users press the shortcuts (`Ctrl + F`, or `Cmd + F` on macOS) when the mouse is inside the viewer container
• It's able to scroll the pages when opening the search popover
• Support link annotations that have the `unsafeUrl` property

Bug fixes

• Typo in full screen change event
• There is a visible page that isn't rendered when setting the zoom level as page width
• The thumbnails aren't rotated after rotating the document

Breaking changes

• The `RotateDirection` provided by the `@react-pdf-viewer/rotate` package now belongs to the `@react-pdf-viewer/core` package:

// v3.1.2 and previous versions
import { RotateDirection } from '@react-pdf-viewer/rotate';

// From v3.2.0
import { RotateDirection } from '@react-pdf-viewer/core';

• The `rotate` function used in the plugins changes the parameter type:

// v3.1.2 and previous versions
rotate(90);
rotate(-90);

// From v3.2.0
rotate(RotateDirection.Forward);
rotate(RotateDirection.Backward);

Bug fixes

• Don't highlight spaces between words when searching for a keyword
• The `clearHighlights` and `clearKeyword()` functions provided by the search plugin should remove all highlights when the keyword is empty
• The current highlight is lost after zooming the document
• The `jumpToMatch()` function provided by the search plugin does not properly highlight keyword when the page is not in the virtual list
• The `ScrollModePluginProps` type isn't defined in the type definitions of the toolbar plugin

Improvement

• The full screen button and menu item are disabled on browsers that don't support full screen APIs. It happens on iOS Safari and iOS Chrome, for example.

Bug fixes

• `onPageChange()` should fire after `onDocumentLoad()`
• The pages aren't layouted properly when they have different dimensions
• The pages are blank initially until users scroll or interact with the page. It happens on some small screen sizes.

New features

• Add new `testId` property to `Spinner`
• The `Viewer` component provides new `scrollMode` option:

import { ScrollMode, Viewer } from '@react-pdf-viewer/core';

<Viewer scrollMode={ScrollMode.Horizontal} />;

• Plugins can register and call the `switchScrollMode` method to switch the scroll mode programatically

Improvements

• The `Viewer` component now works on mobile.

• Improve the performance when rendering a document.

Bug fixes

• Keep the current page after switching the scroll mode
• The Cover component has the same image source when loading different documents
• The default `Spinner` is used when using the `renderLoader` option
• The exit full screen button doesn't look good in dark theme
• The `onPageChange` event fires more than once
• The `renderThumbnailItem` option doesn't work with dynamic document
• The sidebar doesn't fit in its container on Safari
• There is a black area in the full screen mode if the zoom level is small enough

Breaking changes

• It is not possible to access the page element in a plugin with the `getPageElement` function. The method is removed because the pages are rendered dynamically
• The `ScrollMode` provided by the `@react-pdf-viewer/scroll-mode` package now belongs to the `@react-pdf-viewer/core` package:

// v3.0.0 and previous versions
import { ScrollMode } from '@react-pdf-viewer/scroll-mode';

// From v3.1.0
import { ScrollMode } from '@react-pdf-viewer/core';

• The inital scroll mode option provided by the `scrollModePlugin` plugin now belongs to the `Viewer` component:

// v3.0.0 and previous versions
import { scrollModePlugin, ScrollMode } from '@react-pdf-viewer/scroll-mode';

const scrollModePluginInstance = scrollModePlugin({
    scrollMode: ScrollMode.Horizontal,
});

// From v3.1.0
import { ScrollMode } from '@react-pdf-viewer/core';

<Viewer scrollMode={ScrollMode.Horizontal} />;

• There aren't CSS styles provided by the `@react-pdf-viewer/scroll-mode` package:

// v3.0.0 and previous versions
import '@react-pdf-viewer/scroll-mode/lib/styles/index.css';

// From v3.1.0
// Remove the import above

• From v3.1.0, pages are rendered one by one. If you use a custom page renderer, then you have to call the `markRendered` method to mark the page rendered completely. Hence the next page in the queue will be rendered.

// v3.0.0 and previous versions
import type { RenderPageProps } from '@react-pdf-viewer/core';

const CustomPageRender: React.FC<{
    renderPageProps: RenderPageProps;
}> = ({ renderPageProps }) => {
    return (
        <>
            {/* Use the canvas and/or text layers */}
            {renderPageProps.canvasLayer.children}
            {renderPageProps.textLayer.children}

            {/* Your custom components on page ... */}
        </>
    );
};

<Viewer renderPage={(props) => <CustomPageRender renderPageProps={props} />} />;

// From v3.1.0
const CustomPageRender: React.FC<{
    renderPageProps: RenderPageProps;
}> = ({ renderPageProps }) => {
    React.useEffect(() => {
        if (renderPageProps.canvasLayerRendered && renderPageProps.textLayerRendered) {
            renderPageProps.markRendered(renderPageProps.pageIndex);
        }
    }, [renderPageProps.canvasLayerRendered, renderPageProps.textLayerRendered]);

    return (
        <>
            {/* Use the canvas and/or text layers */}
            {renderPageProps.canvasLayer.children}
            {renderPageProps.textLayer.children}

            {/* Your custom components on page ... */}
        </>
    );
};

<Viewer renderPage={(props) => <CustomPageRender renderPageProps={props} />} />;

New features

• Add new `testId` property to `MenuItem`, `MinimalButton`, `PrimaryButton`
• Be able to customize the button to exit the full screen mode:

const fullScreenPluginInstance = fullScreenPlugin({
    renderExitFullScreenButton: (props) => (
        <div
            style={{
                bottom: '1rem',
                position: 'fixed',
                right: '1rem',
            }}
        >
            <button onClick={props.onClick}>Exit full screen</button>
        </div>
    ),
});

• The full screen plugin allows to set the full screen element. The following code will include the pages container and the toolbar in the full screen mode:

const fullScreenPluginInstance = fullScreenPlugin({
    // `pagesContainer` is the pages container
    getFullScreenTarget: (pagesContainer) => pagesContainer.closest('[data-testid="default-layout__body"]'),
}),

• The thumbnail plugin adds new `renderSpinner` property that can be used to replace the default `Spinner` component. This example displays custom loading indicators when loading the cover or thumbnail of a page:

const thumbnailPluginInstance = thumbnailPlugin({
    renderSpinner: () => <div className="square-spinner" />,
});

• The `Thumbnails` component adds new `renderThumbnailItem` property that is used to customize the thumbnail renderer:

const renderThumbnailItem = (props: RenderThumbnailItemProps) => (
    <div
        key={props.pageIndex}
        onClick={props.onJumpToPage}
        style={{
            backgroundColor: props.pageIndex === props.currentPage ? 'rgba(0, 0, 0, 0.3)' : '#fff',
            cursor: 'pointer',
            padding: '0.5rem',
        }}
    >
        {props.renderPageThumbnail}
    </div>
);

const thumbnailPluginInstance = thumbnailPlugin();
const { Thumbnails } = thumbnailPluginInstance;

<Thumbnails renderThumbnailItem={renderThumbnailItem} />;

Improvements

• Add `data-testid` attribute to buttons in the toolbar
• The `Cover` component uses the image instead of canvas tag
• The default layout shouldn't have a horizontal scrollbar when the default scale isn't set

Bug fixes

• Navigating between search results should be the same as their appearances on pages
• The internal links don't work properly in some cases
• The thumbnails are stuck at loading spinner
• The `Cover` component position isn't correct
• The number of pages slot `<NumberOfPages />` isn't correct when using the `renderToolbar`
• There is an exception of `React has detected a change in the order of Hooks` when switching documents

New features

• The `Button` component has new `testId` property that is identical with the `data-testid` attribute
• The Scroll Mode plugin provides new function to switch mode programmatically:

const scrollModePluginInstance = scrollModePlugin();
const { switchScrollMode } = scrollModePluginInstance;

// Switch to the wrapped mode
switchScrollMode(ScrollMode.Wrapped);

const defaultLayoutPluginInstance = defaultLayoutPlugin({
    toolbarPlugin: {
        fullScreenPlugin: {
            onEnterFullScreen: (zoom) => {
                zoom(SpecialZoomLevel.PageFit);
                defaultLayoutPluginInstance.toolbarPluginInstance.scrollModePluginInstance.switchScrollMode(
                    ScrollMode.Wrapped
                );
            },
            onExitFullScreen: (zoom) => {
                zoom(SpecialZoomLevel.PageWidth);
                defaultLayoutPluginInstance.toolbarPluginInstance.scrollModePluginInstance.switchScrollMode(
                    ScrollMode.Horizontal
                );
            },
        },
    },
});

Improvements

• Cache pages' labels. So we won't see blink in the current page label when navigating between pages
• Keep the file name when downloading a file opened from local
• It's possible to remove the sidebar created by the default layout plugin:

const defaultLayoutPluginInstance = defaultLayoutPlugin({
    sidebarTabs: () => [],
});

Bug fixes

• Can't use special characters such as `(`, `)`, `[`, `]`, `*` in the keyword
• Downloading document doesn't work on iOS Safari and iOS Chrome
• The Get File plugin doesn't work with a file which is opened with credentials
• The highlight areas aren't displayed
• The `selectedText` prop of `RenderHighlightContentProps` isn't correct

New feature

• The `Zoom` and `ZoomPopover` components provided by the zoom plugin add new option to customize the zoom levels

<Zoom levels={[0.5, 1, 2, 3, 4]} />

<ZoomPopover levels={[0.5, 1, 2, 3, 4]} />

Bug fix

• Clicking the Search button scrolls to the top of page

New features

• Add new `trigger` option for the highlight plugin:

import { Trigger } from '@react-pdf-viewer/highlight';

const highlightPluginInstance = highlightPlugin({
    trigger: Trigger.None,
});

• The render props of the `CurrentPageLabel` component provided by the Page Navigation plugin includes new `pageLabel` property. It is useful if the page has a label that isn't the same as its page number:

const { CurrentPageLabel } = pageNavigationPluginInstance;

<CurrentPageLabel>
    {(props) => (
        <>
            {props.currentPage + 1}
            {props.pageLabel === `${props.currentPage + 1}` ? '' : ` (${props.pageLabel})`} of {props.numberOfPages}
        </>
    )}
</CurrentPageLabel>;

• The Thumbnails component displays the page labels if there are. You also can customize the page labels:

const thumbnailPluginInstance = thumbnailPlugin({
    renderCurrentPageLabel: (props) => (
        <>
            {props.pageIndex + 1}
            {props.pageLabel !== `${props.pageIndex + 1}` && `(${props.pageLabel})`}
        </>
    ),
});
const { Thumbnails } = thumbnailPluginInstance;

<Thumbnails />;

• The toolbar plugin provides the `renderDefaultToolbar` function to create a custom toolbar from the default toolbar easily. The following sample code prepends `of` to the `NumberOfPages` component:

import type { ToolbarSlot, TransformToolbarSlot } from '@react-pdf-viewer/toolbar';

const { renderDefaultToolbar, Toolbar } = toolbarPluginInstance;

const transform: TransformToolbarSlot = (slot: ToolbarSlot) => {
    const { NumberOfPages } = slot;
    return Object.assign({}, slot, {
        NumberOfPages: () => (
            <>
                of <NumberOfPages />
            </>
        ),
    });
};

// Render the toolbar
<Toolbar>{renderDefaultToolbar(transform)}</Toolbar>;

Improvement

• Disable the printing functionality if the document doesn't allow to print

Bug fixes

• Can't resize the sidebar when using with the Fluent UI library
• Fix the TypeScript definition of the Cover component
• Fix an edge case where there are extra empty pages when printing a document

Improvement

New features

• The `core` package provides new `Splitter` component
• The thumbnail plugin provides new `Cover` component that shows the thumbnail of a particular page:

const { thumbnailPluginInstance } = thumbnailPlugin();
const { Cover } = thumbnailPluginInstance;

// Thumbnail of the first page
<Cover getPageIndex={_ => 0} />

// Thumbnail of the last page
<Cover getPageIndex={props => props.numPages - 1} />

• Add new `onDocumentAskPassword` event that is triggered when a protected document requires a password to open:

const handleAskPassword = (e: DocumentAskPasswordEvent) => {
    // ...
};

<Viewer onDocumentAskPassword={handleAskPassword} />;

Improvements

• Automatically focus on the keyword input in the search popover
• Press `Enter` to submit the password when opening a protected document
• Show the page numbers for thumbnails
• The Default Layout plugin allows to resize the sidebar
• The plugin instances which can be accessed from an instance of the Default Layout or Toolbar plugin should be readonly
• Support more shortcuts

// Use the standalone open plugin
const openPluginInstance = openPlugin({
    enableShortcuts: false,
});

// Use the default layout plugin
const defaultLayoutPluginInstance = defaultLayoutPlugin({
    toolbarPlugin: {
        openPlugin: {
            enableShortcuts: false,
        },
    },
});

New features

• Support RTL. You can use a RTL language such as Arabic:

import { TextDirection, Viewer } from '@react-pdf-viewer/core';

<Viewer
    theme={{
        direction: TextDirection.RightToLeft,
    }}
/>;

• The `RenderViewer` type includes the theme context

Bug fixes

• The highlighting elements should be shown below the text, so users can still select the text
• There is an exception when opening a password protected document

New feature

import { searchPlugin } from '@react-pdf-viewer/search';

const searchPluginInstance = searchPlugin();
const { setTargetPages } = searchPluginInstance;

// Only search in even pages
setTargetPages((targetPage) => targetPage.pageIndex % 2 === 0);

// Only search in the page 4
setTargetPages((targetPage) => targetPage.pageIndex === 3);

Improvements

• Allow to change the theme from outside of the `Viewer` component
• When the default scale is set to a special zoom level, we should keep it when resizing the window
• The `onDocumentLoad` event and plugins' `PluginOnDocumentLoad` callback provide access to the current opened file which contains the `data` and `name` properties:

const handleDocumentLoad = (e: DocumentLoadEvent) => {
    console.log(e.file.name, e.file.data);
};

<Viewer onDocumentLoad={handleDocumentLoad} />;

Bug fixes

• Can't close the menu when using with the Fluent UI
• The `activateTab()` method provided by the default layout plugin shouldn't toggle the tab
• The `LocalePopover` component doesn't update the localization
• The pages' container overflows on initial render when setting the default scale to `SpecialZoomLevel.PageWidth`

Improvement

Bug fixes

• Automatically scroll to the top of page when opening a menu
• Fix the warning when pressing the Escape key to close a modal

New features

• Add new `onSwitchTheme` option that allows to track if users switch theme. The following snippet demonstrates an example that the current theme is stored in the local storage, and is loaded back in the next user's visit:

const handleSwitchTheme = (theme: string) => {
    localStorage.setItem('theme', theme);
};
const theme = localStorage.getItem('theme') || 'light';

<Viewer theme={theme} onSwitchTheme={handleSwitchTheme} />;

• Add new `jumpToMatch` function which jumps to the given match
• The `highlight` function now returns a `Promise` that holds the results. Each result also contains the matching text
• The `core` package provides `isMac` function

Improvements

• Add ARIA attributes to `Icon`, `Menu`, `MenuDivider`, `MenuItem`, `MinimalButton`, `Modal`, `Popover`, `TextBox`, `Tooltip` components
• Add ARIA attributes to pages and thumbnails
• Add ARIA attributes to internal links of the document
• When the shortcuts are enabled, the associal buttons will have the `aria-keyshortcuts` attributes
• Use the keyboard to navigate between components:

• Add a background color to the current search highlight
• Show a loading indicator while searching for a keyword
• The `Spinner` component adds new `size` property

Bug fixes

• Custom search control isn't rendered
• Pressing shortcuts effects all viewer instances in the same page. The shortcuts should be enabled when the viewer gets focused.
• Remove `br` elements generated by the recent versions of pdf.js before rendering the text layer
• Remove `keyCode` usages because it's deprecated
• The print progress container loses the border
• The search popover isn't shown until the document is loaded

Improvements

• Move the CSS variables of the default theme to `:root`, so we can use components (`Button`, `Menu`, `Tooltip`, etc.) outside of the `Viewer`
• Update the `DownloadIcon`, `ExitFullScreenIcon`, `FullScreenIcon` and `OpenFileIcon` icons

Bug fixes

• Remove duplicate borders of keyword input
• Search results are not highlighted
• The Search plugin can cause a re-render

/* Old version */
.rpv-search-highlight {
    ...;
}
.rpv-search-highlight-current {
    ...;
}

/* From v2.6.0 */
.rpv-search__highlight {
    ...;
}
.rpv-search__highlight--current {
    ...;
}

New features

• The core package provides new `TextBox` component
• Support themes. You can create a custom theme with new `theme` option:

<Viewer theme="bootstrap" />

.rpv-core__viewer--bootstrap {
    /* Custom the background color of toolbar in the default layout */
    --rpv-default-layout__toolbar-background-color: #eee;
}

• Add new theme plugin that provides components for switching between the dark and light themes
• The toolbar Slot has new `SwitchTheme` and `SwitchThemeMenuItem` components

Improvements

• Tweak toggle icons in bookmark items
• The bookmark plugin provide new icons: `DownArrowIcon` and `RightArrowIcon`
• Improve text selection in the highlight plugin
• You can enable or disable shortcuts in the print and zoom plugins:

const printPluginInstance = printPlugin({
    // The shortcuts are enabled by default
    enableShortcuts: false,
});

const zoomPluginInstance = zoomPlugin({
    // The shortcuts are enabled by default
    enableShortcuts: false,
});

Bug fixes

• Can't close popovers after scrolling
• Can't open any popover after printing
• Icons in menu items aren't centered horizontally
• There is an exception when jumping to the next or previous match if the keyword isn't found

Breaking changes

• The toolbar plugin doesn't include the drop plugin anymore. In order to use the drop plugin, you have to register it
• The `Button` component provided by the `core` package is renamed to `MinimalButton`
• The option `prefixClass` of `Viewer` is removed

New features

• The default layout is responsive in different screen sizes
• You can add more options that will be passed to the pdf.js `getDocument` API:

<Viewer
    fileUrl="..."
    transformGetDocumentParams={(options: PdfJs.GetDocumentParams) =>
        Object.assign({}, options, {
            disableRange: false,
            disableStream: false,
        })
    }
/>

• Provide more reusable components:

Improvements

• Decrease the number of renders from twice to once when setting the default scale
• The `Button` and `MenuItem` components have disabled state. For example, the button for going to the first page will be disabled if we're at the first page
• The icons use the current color instead of hard coded one. It's easier for us to create themes

Bug fixes

• Doesn't work with NextJS because `navigator` isn't defined
• Some bookmarks are hidden initially
• The `initialPage` and `defaultScale` options don't work together
• There are big spaces between thumbnails
• Zoom the document best inside the container initially

Breaking changes

• If you are creating a custom toolbar or buttons to go to particular pages, then the following props are renamed:

Improvements

• Automatically scroll to the thumbnail that represents the current page
• Display the progress properly when printing a big document
• Improve the performance of preparing pages for print such as using a shared `canvas` element for all pages
• Keep showing a spinner until the canvas layer is rendered completely
• The print plugin supports documents whose pages have different dimensions

Bug fix

• Clicking on an internal link jumps to an incorrect page (one page after the destination one)

Improvements

• Display the current page number in the right
• Make the content of annotation scrollable
• Support shortcuts

Bug fixes

• Can't delete the last remaining digit in the page number input
• Properly check whether or not the `fileUrl` changes
• Fix the issue where we see the spinner if the document has a single page and the height is smaller than the viewer's height
• Can't open the downloaded file if it was loaded with `Uint8Array`
• Annotation popup can be displayed under the previous or next page
• When users download a document loaded with `Uint8Array`, the download file is named as `document.pdf` instead of the document blob
• Clicking a bookmark doesn't jump to the destination properly in the first time if the bookmark also requires to zoom the document to fit the width

Bug fixes

• Clicking the Download button doesn't work. It only works the file when scrolling to the second page
• Using the Default Layout plugin, we can't scroll between pages on Safari 14
• The Open file button covers other elements, so we can't click on the Download or Print buttons. This issue only happens on Safari 14

New features

• The Search plugin provides methods to search for given keywords programatically:

import { searchPlugin } from '@react-pdf-viewer/search';
const searchPluginInstance = searchPlugin();

const { clearHighlights, highlight, jumpToNextMatch, jumpToPreviousMatch } = searchPluginInstance;

<button onClick={() => highlight(['document', 'PDF'])}>Highlight: document, PDF</button>;

• It's possible to add custom styles for highlighted area based on the keyword:

const searchPluginInstance = searchPlugin({
    onHighlightKeyword: (props: OnHighlightKeyword) => {
        if (props.keyword.source === 'document') {
            props.highlightEle.style.outline = '2px dashed blue';
            props.highlightEle.style.backgroundColor = 'rgba(0, 0, 0, .1)';
        }
    },
});

• The Zoom plugin exposes the `zoomTo` function:

const { zoomTo } = zoomPluginInstance;

// Zoom to a given level
zoomTo(1.5);
zoomTo(SpecialZoomLevel.PageFit);

• The Page Navigation plugin provides the `jumpToPage` function:

const { jumpToPage } = pageNavigationPluginInstance;

// Jump to the third page
jumpToPage(2);

• It's possible to retrieve the instances of Attachment, Bookmark, Thumbnail, Toolbar plugins from the Default Layout plugin instance.

const defaultLayoutPluginInstance = defaultLayoutPlugin();

const { attachmentPluginInstance, bookmarkPluginInstance, thumbnailPluginInstance, toolbarPluginInstance } =
    defaultLayoutPluginInstance;

const toolbarPluginInstance = toolbarPlugin();

const {
    dropPluginInstance,
    fullScreenPluginInstance,
    getFilePluginInstance,
    openPluginInstance,
    pageNavigationPluginInstance,
    printPluginInstance,
    propertiesPluginInstance,
    rotatePluginInstance,
    scrollModePluginInstance,
    searchPluginInstance,
    selectionModePluginInstance,
    zoomPluginInstance,
} = toolbarPluginInstance;

Improvements

• Support Next.js integration
• Fix a warning in the Console when using with Next.js
• The `SingleKeyword` type in the Search plugin supports flags:

interface FlagKeyword {
    keyword: string;
    matchCase?: boolean; // `false` by default
    wholeWords?: boolean; // `false` by default
}

type SingleKeyword = string | RegExp | FlagKeyword;

const searchPluginInstance = searchPlugin({
    keyword: {
        keyword: 'document',
        matchCase: true,
    },
});

Bug fixes

• The Search plugin can find text that belongs to multiple `span` elements
• Fix the type definitions of the `MoreActionsPopover` component in the Toolbar plugin

Breaking change

• The `Observer` component is removed from the `@react-pdf-viewer/core` package

Improvements

• Lazy load the document. The PDF document will be loaded if the viewer container is visible in the viewport.

Bug fixes

• `Worker was destroyed`
• `Cannot read property 'sendWithPromise' of null`

Improvements

• The Full Screen plugin provides new callbacks that are triggered after entering and exiting the full screen mode

import { SpecialZoomLevel } from '@react-pdf-viewer/core';
import { fullScreenPlugin } from '@react-pdf-viewer/full-screen';

const fullScreenPluginInstance = fullScreenPlugin({
    // Zoom to fit the screen after entering and exiting the full screen mode
    onEnterFullScreen: (zoom) => {
        zoom(SpecialZoomLevel.PageFit);
    },
    onExitFullScreen: (zoom) => {
        zoom(SpecialZoomLevel.PageFit);
    },
});

Bug fixes

• The style files are missing in the Highlight plugin
• Render highlight annotations formed by quadrilaterals
• The popup annotations aren't shown if they are children of highlight annotations
• Clicking a destination (bookmark, for example) with name of `FitH` or `FitBH` throws an exception

New features

• New `highlight` plugin provides the ability of selecting and adding notes for text in the document
• The Default Layout plugin allows to customize the tabs:

// `defaultTabs` is the list of default tabs which lists thumbnails, bookmarks and attachments respetively
const defaultLayoutPluginInstance = defaultLayoutPlugin({
    sidebarTabs: defaultTabs => { ... }
});

const { activateTab } = defaultLayoutPluginInstance;

// Activate a tab
// activateTab(index);

Breaking changes

• The `getPagesRef` method in plugins are changed to `getPagesContainer`:

// Before v2.3.0
interface PluginFunctions {
    getPagesRef(): React.RefObject<HTMLDivElement>;
}

// From v2.3.0
interface PluginFunctions {
    getPagesContainer(): HTMLElement;
}