React Pdf Viewer Versions Save

New features

• The plugin exposes new functions:

Function	Destination
jumpToNextDestination	Jump to the next destination
jumpToPreviousDestination	Jump to the previous destination

• 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:

Shortcut	Operating System	Action
Command + ArrowLeft	macOS	Jump to the previous bookmark destination
Alt + ArrowLeft	Windows	Same as above
Command + ArrowRight	macOS	Jump to next bookmark destination
Alt + ArrowRight	Windows	Same as above

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
• Viewer 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={ProtectedView} />

• 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):

Shortcut	Operating System	Action
Command + ArrowLeft	macOS	Jump to previous clicked link annotation
Alt + ArrowLeft	Windows	Same as above

• 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} />;

You can switch to the page scrolling mode from the toolbar.

• New three page viewmodes:

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

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

Mode	Description
ViewMode.SinglePage	The default mode. View single page continuously
ViewMode.DualPage	View two pages each time
ViewMode.DualPageWithCover	View two pages each time. The first page is displayed as a cover

• 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

Fix bugs that might happen with a document whose pages have different dimensions

• 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
• RenderBookmarkItemProps includes new path property that indicates the path from each bookmark item to the root
• SelectionData provides more information about the selected text including:

Property	Type	Description
selectedText	string	The selected text
divTexts	DivText[]	List of text items contain the selected text

A DivText item consists of

Property	Type	Description
divIndex	number	The zero-based text element rendered by the text layer
pageIndex	number	The zero-based page index
textContent	string	The text content of text element

• 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;
}

You have to check if it exists before using it:

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. Is is a function that takes the current document and returns the list of zero-based index 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[],
});

Here are some examples:

// 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),
});

The option is also available when using the default layout plugin:

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

You don't have to implement functions that return popular pages numbers. The print plugin provides useful functions for most popular cases:

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

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

Function	Description
getAllPagesNumbers	Returns all pages numbers of the document
getCustomPagesNumbers	Returns the custom pages numbers. The input is a string consists of given pages or ranges of pages. For example:
	1, 2, 3
	1-3
	1-3, 5, 8-11
getEvenPagesNumbers	Returns even pages numbers
getOddPagesNumbers	Returns odd pages numbers

• 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;

The print function is also available if you use the default layout plugin:

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 highlight elements when searching for a keyword:

const searchPluginInstance = searchPlugin({
    renderHighlights: (highlightPositions: HighlightPosition[]) => (
        // Your custom highlight 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.

Shortcut	Action
PageUp or Alt + ArrowUp	Go to the previous page
PageDown or Alt + ArrowDown	Go to the next page

The shortcuts are enabled by default. It's possible to disable them, for example:

// 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 plugins

New feature

• It's possible to set the initial tab

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

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

According to the PDF specifications, the initial tab can be determined based on the document's page mode. If you want to follow that behaviour, then you can use the setInitialTabFromPageMode function:

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

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

Improvement

• Smooth scroll when jumping to a given page or destination (clicking a bookmark, for example)

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