Releases: react-pdf-viewer/react-pdf-viewer
New property to disable smooth scroll
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 newwidth
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 theinitialPage
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 thejumpToDestination
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);
Thumbnails direction
New features
- Add
pagesContainerRef
toRenderViewer
, 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 totransformSize
3 viewmodes
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 newjumpToPreviousPage
andjumpToNextPage
to jump to the previous and next pages -
The
scroll-mode
plugin provides newDualPageCoverViewModeIcon
,DualPageViewModeIcon
andPageScrollingIcon
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
Margin between pages
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
andpageWidth
properties inRenderViewer
are replaced with thepageSizes
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.
Improve Highlight plugin
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 newpath
property that indicates the path from each bookmark item to the rootSelectionData
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 newisDocumentLoaded
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
andtitle
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
andendPageIndex
properties ofSelectionData
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.
TheSelectionData
property inRenderHighlightContentProps
andRenderHighlightTargetProps
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 ...
}
Improve Bookmark plugin
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) orCtrl
+ArrowUp
(on Windows) will bring users to the previous clicked link annotation.
You can disable that shortcuts via theenableShortcuts
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
Improve print plugin
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
Customize the highlight elements
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 aPromise
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
Set the initial tab
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
Support web optimized documents
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