Customizing Viewer Toolbar / Header

This only applies to Legacy UI

This way of customizing the header only applies to the Legacy UI which is deprecated. We strongly recommend using the Modular UI for improved performance and features. If your application currently uses the Legacy UI and you want to migrate to Modular UI, refer to our Migration Guide to V11 Modular UI for step-by-step instructions.

There are a number of ways you may want to customize the header. To name a few:

  • Removing all annotation tool buttons
  • Reordering annotation tool buttons
  • Replacing the existing view controls buttons with custom buttons
  • Adding a custom annotation tool button
  • Replace the entire header with different items in smaller screens

When in the legacy UI mode, the WebViewer UI provides a flexible API to easily handle each of these cases and more.

To learn about the structure and different types of items, you can start reading from header composition and header items. Otherwise, you can jump straight to examples and relevant APIs.

Header Composition

There are two main types of headers. The first one is the top header. This header defaults to navigation tools, opening sub-menus and panels. Also in the center you will see a collection of toolbar group labels, called ribbons.

Apryse Docs Image

Selecting a toolbar group other than View will reveal the tools header. Each tools header has a different combination of tools. They can be modified individually.

Apryse Docs Image

Each header is represented by an array of header items. The array can be edited to add/remove/reorder items. The API, setHeaderItems, will provide the top header object as a function argument by default. To access a tools header please see the examples in the API link.

Customizing Ribbons

Apryse Docs Image

New in version 7.0, are the ribbons in the top header. This is a collection of toolbar groups. Each group reveals a second tools header that contain a different set of tools. There are various API calls that can be use to customize the ribbons.

To set a default to toolbar to load on startup, call setToolbarGroup. Alternatively, it can be called at any time to change the current toolbar group.

1WebViewer(...)
2 .then(instance => {
3 // Sets the current toolbar group
4 instance.UI.setToolbarGroup('toolbarGroup-Insert');
5 });

If you want to hide a specific toolbar group, like other DOM elements, they can be hidden by using disableElements.

1WebViewer(...)
2 .then(instance => {
3 // hide the Shapes, Edit and Insert toolbar groups.
4 instance.UI.disableElements(['toolbarGroup-Shapes']);
5 instance.UI.disableElements(['toolbarGroup-Edit']);
6 instance.UI.disableElements(['toolbarGroup-Insert']);
7 });

Alternatively, you may only want to use one toolbar group and hide the ribbons altogether. This may be done with code similar to the following:

1WebViewer(...)
2 .then(instance => {
3 // hide the ribbons
4 instance.UI.disableElements(['ribbons']);
5 // set the default toolbar group to the Shapes group
6 instance.UI.setToolbarGroup('toolbarGroup-Shapes');
7 });

Lastly, you can move specific tools from one group to another. Below is an example of moving the line tool from the Shapes toolbar group to the Annotate toolbar group.

1// Moving the line tool from the 'Shapes' toolbar group to the 'Annotate' toolbar group
2WebViewer(...)
3 .then(function(instance) {
4 instance.UI.setHeaderItems(function(header) {
5 header.getHeader('toolbarGroup-Annotate').push({
6 type: 'toolGroupButton',
7 toolGroup: 'lineTools',
8 dataElement: 'lineToolGroupButton',
9 title: 'annotation.line',
10 });
11 header.getHeader('toolbarGroup-Shapes').delete(6);
12 });
13 });

Header Items

Apryse Docs Image

Header items are objects with certain properties. If you wish to add a header item, it is important for you to understand what type it is and what properties should be used.

ActionButton

ActionButton triggers an action. The button has no active state.

Properties

  • type (string) - Must be set to actionButton.
  • img (string) - Path to an image or base64 data. Can also be the filename of a .svg from the WebViewer

assets/icons/ folder (i.e. calibrate to use calibrate.svg).

  • onClick (function) - Function to be triggered on click.
  • title (string, optional) - Tooltip of the button.
  • dataElement (string, optional) - Option to set data-element value of the button element. It can be used to disable/enable the element.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

JavaScript

1const newActionButton = {
2 type: 'actionButton',
3 img: 'path/to/image',
4 onClick: () => {
5 alert('Hello world!');
6 },
7 dataElement: 'alertButton',
8 hidden: [ 'mobile' ]
9};

StatefulButton

StatefulButton is a customizable button. You can decide how many states it has, what state is active and when to update the state.

Properties

  • type (string) - Must be set to statefulButton.
  • initialState (string) - String that is one of states object's keys.
  • states (object) - Object in the shape of: { nameOfState1: state1, nameOfState2: state2, ... }
    • Properties of a state:
      • img (string, optional): Path to an image or base64 data. Can also be the filename of a .svg from the WebViewer assets/icons/ folder (i.e. calibrate to use calibrate.svg).
      • getContent (function, optional): Function to be called when you update the state. Define this property if you don't use the img property for this button. Argument: activeState.
      • onClick (function): Function to be triggered on click. Arguments: update, activeState.
      • Any other properties you need.
  • mount (function) - Function to be called after the button is mounted into DOM
  • unmount (function, optional) - Function to be called before the button is unmounted from DOM.
  • dataElement (string, optional) - String to set data-element value of the button element. It can be used to disable/enable the element.
  • title (string, optional) - Tooltip of the button.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

A stateful button that shows the count. And when you click it, it will increment the counter by 1.

JavaScript

1const countButton = {
2 type: 'statefulButton',
3 initialState: 'Count',
4 states: {
5 Count: {
6 number: 1,
7 getContent: activeState => {
8 return activeState.number;
9 },
10 onClick: (update, activeState) => {
11 activeState.number += 1;
12 update();
13 }
14 }
15 },
16 dataElement: 'countButton'
17};

A stateful button that shows the current page number. And when you click it, the document will go to next page. If you are already at the last page, the document will go to the first page.

1const nextPageButton = {
2 type: 'statefulButton',
3 initialState: 'Page',
4 states: {
5 Page: {
6 // Checkout https://docs.apryse.com/api/web/WebViewerInstance.html to see more APIs related with viewerInstance
7 getContent: instance.UI.getCurrentPageNumber,
8 onClick: () => {
9 const currentPage = instance.UI.getCurrentPageNumber();
10 const totalPages = instance.UI.getPageCount();
11 const atLastPage = currentPage === totalPages;
12
13 if (atLastPage) {
14 instance.UI.goToFirstPage();
15 } else {
16 instance.UI.goToNextPage();
17 }
18 }
19 }
20 },
21 mount: update => {
22 // Checkout https://docs.apryse.com/api/web/Core.DocumentViewer.html to see more APIs and events with docViewer
23 // We want to update this button when page number changes so it can have the correct content;
24 instance.Core.documentViewer.addEventListener('pageNumberUpdated.nextPageButton', update);
25 },
26 unmount: () => {
27 instance.Core.documentViewer.removeEventListener('pageNumberUpdated.nextPageButton');
28 },
29 dataElement: 'nextPageButton'
30};

A stateful button that changes the fit mode of the document.

This button is in our built-in UI, checkout it out at https://showcase.apryse.com.

Apryse Docs Image
1const fitButton = {
2 type: 'statefulButton',
3 initialState: 'FitWidth',
4 states: {
5 FitWidth: {
6 img: 'path/to/fitWidth/image',
7 onClick: () => {
8 instance.UI.setFitMode(instance.UI.FitMode.FitWidth);
9 },
10 },
11 FitPage: {
12 img: 'path/to/fitPage/image',
13 onClick: () => {
14 instance.UI.setFitMode(instance.UI.FitMode.FitPage);
15 },
16 }
17 },
18 mount: update => {
19 const fitModeToState = fitMode => {
20 // the returned state should be the opposite of the new current state
21 // as the opposite state is what we want to switch to when the button
22 // is clicked next
23 if (fitMode === instance.Core.documentViewer.FitMode.FitPage) {
24 return 'FitWidth';
25 } else if (fitMode === instance.Core.documentViewer.FitMode.FitWidth) {
26 return 'FitPage';
27 }
28 };
29
30 instance.Core.documentViewer.addEventListener('fitModeUpdated.fitbutton', fitMode => {
31 update(fitModeToState(fitMode));
32 });
33 },
34 unmount: () => {
35 instance.Core.documentViewer.removeEventListener('fitModeUpdated.fitbutton');
36 },
37 dataElement: 'fitButton',
38 hidden: ['mobile']
39};

ToggleElementButton

ToggleElementButton opens/closes a UI element. The button is in an active state when the UI element is open.

Properties

  • type (string) - Must be set to toggleElementButton.
  • img (string) - Path to an image or base64 data. Can also be the filename of a .svg from the WebViewer assets/icons/ folder (i.e. calibrate to use calibrate.svg).
  • element (string) - data-element attribute value of the UI element to be opened/closed.
  • dataElement (string, optional) - Option to set data-element value of the button element. It can be used to disable/enable the element.
  • title (string, optional) - Tooltip of the button.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

JavaScript

1const newToggleElementButton = {
2 type: 'toggleElementButton',
3 img: 'path/to/image',
4 element: 'leftPanel',
5 dataElement: 'leftPanelButton',
6 hidden: [ 'mobile' ]
7};

ToolButton

ToolButton activates a WebViewer tool. The button is in an active state when the tool is activated. To learn more about customizing annotation tools and tool buttons, see customizing tools.

Properties

  • type (string) - Must be set to toolButton.
  • toolName (string) - Name of the tool, which is either the key from toolModeMap or the name you registered your custom tool with. For custom tool registration, refer to registerTool.
  • title (string, optional) - Tooltip of the button.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

JavaScript

1const newToolButton = {
2 type: 'toolButton',
3 toolName: 'AnnotationCreateFreeText',
4 hidden: [ 'mobile' ]
5}

ToolGroupButton

A ToolGroupButton shows the tools available to that tool group. Unless the img option is set, the button displays the image of one of the group members. The button is in an active state when any tool in the group is active. To learn more about customizing annotation tools and tool buttons, see customizing tools.

Apryse Docs Image

Properties

  • type (string) - Must be set to 'toolGroupButton'.
  • toolGroup (string) - Name of the tool group. In the default viewer, there are freeHandTools, textTools, shapeTools and miscTools.
  • img (string, optional) - Path to an image or base64 data. Can also be the filename of a .svg from the WebViewer assets/icons/ folder (i.e. calibrate to use calibrate.svg).
  • dataElement (string, optional) - Option to set data-element value of the button element. It can be used to disable/enable the element.
  • title (string, optional) - Tooltip of the button.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

JavaScript

1const newToolGroupButton = {
2 type: 'toolGroupButton',
3 toolGroup: 'shapeTools',
4 dataElement: 'shapeToolGroupButton',
5 hidden: [ 'mobile' ]
6};

CustomElement

CustomElement takes a render function and renders DOM elements or React components. You may want to use this when the buttons above don't suffice.

Properties

  • type (string) - Must be set to 'customElement'.
  • title (string, optional) - Tooltip of the button.
  • render (func) - Function that returns DOM elements or React components
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

JavaScript

1const renderSlider = () => {
2 const slider = document.createElement('input');
3 slider.type = 'range';
4 slider.oninput = () => {
5 // Do something
6 };
7
8 return slider;
9}
10
11const newCustomElement = {
12 type: 'customElement',
13 render: renderSlider
14};

In React jsx:

JavaScript

1const Slider = () => {
2 return (
3 <input
4 type="range"
5 onInput={() => { /* Do something */ }}
6 >
7 </input>
8 );
9}
10
11const newCustomElement = {
12 type: 'customElement',
13 render: () => <Slider />
14};

Spacer

Spacer is just a div with flex: 1 to occupy any remaining space. It is used to push the buttons to each side on the default header.

Properties

  • type (string) - Must be set to 'spacer'.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

JavaScript

1const newSpacer = {
2 type: 'spacer',
3 hidden: [ 'mobile' ]
4};

Divider

Divider renders a vertical bar with some margin to separate item groups.

Properties

  • type (string) - Must be set to 'divider'.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

JavaScript

1const newDivider = {
2 type: 'divider',
3 hidden: [ 'mobile' ]
4};

Examples

Adding a custom save button

1WebViewer(...)
2 .then(instance => {
3 instance.UI.setHeaderItems(header => {
4 header.push({
5 type: 'actionButton',
6 img: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M0 0h24v24H0z" fill="none"/><path d="M17 3H5c-1.11 0-2 .9-2 2v14c0 1.1.89 2 2 2h14c1.1 0 2-.9 2-2V7l-4-4zm-5 16c-1.66 0-3-1.34-3-3s1.34-3 3-3 3 1.34 3 3-1.34 3-3 3zm3-10H5V5h10v4z"/></svg>',
7 onClick: () => {
8 // save the annotations
9 }
10 });
11 });
12 });

After you added a custom save button, here is a code sample you can add inside of onClick function for saving a PDF.

Hiding ribbons and pushing tools to top header

1WebViewer(...)
2 .then(instance => {
3 instance.UI.setHeaderItems(function(header) {
4 // get the tools overlay
5 const toolsOverlay = header.getHeader('toolbarGroup-Annotate').get('toolsOverlay');
6 header.getHeader('toolbarGroup-Annotate').delete('toolsOverlay');
7 // add the line tool to the top header
8 header.getHeader('default').push({
9 type: 'toolGroupButton',
10 toolGroup: 'lineTools',
11 dataElement: 'lineToolGroupButton',
12 title: 'annotation.line',
13 });
14 // add the tools overlay to the top header
15 header.push(toolsOverlay);
16 });
17 // hide the ribbons and second header
18 instance.UI.disableElements(['ribbons']);
19 instance.UI.disableElements(['toolsHeader']);
20 });

Adding a custom dropdown

JavaScript (v8.0+)

1WebViewer(...)
2 .then(instance => {
3 const { documentViewer } = instance.Core;
4 const document = instance.UI.iframeWindow.document;
5
6 instance.UI.setHeaderItems(header => {
7 const parent = documentViewer.getScrollViewElement().parentElement;
8
9 const menu = document.createElement('div');
10 menu.classList.add('Overlay');
11 menu.classList.add('FlyoutMenu');
12 menu.style.padding = '1em';
13
14 const downloadBtn = document.createElement('button');
15 downloadBtn.textContent = 'Download';
16 downloadBtn.onclick = () => {
17 // Download
18 };
19
20 menu.appendChild(downloadBtn);
21
22 let isMenuOpen = false;
23
24 const renderCustomMenu = () => {
25 const menuBtn = document.createElement('button');
26 menuBtn.textContent = 'My Menu';
27
28 menuBtn.onclick = () => {
29 if (isMenuOpen) {
30 parent.removeChild(menu);
31 } else {
32 menu.style.left = `${document.body.clientWidth - (menuBtn.clientWidth + 40)}px`;
33 menu.style.right = 'auto';
34 menu.style.top = '40px';
35 parent.appendChild(menu);
36 }
37
38 isMenuOpen = !isMenuOpen;
39 };
40
41 return menuBtn;
42 };
43
44 const newCustomElement = {
45 type: 'customElement',
46 render: renderCustomMenu,
47 };
48
49 header.push(newCustomElement);
50 });
51 });

JavaScript (v6.0+)

1WebViewer(...)
2 .then(instance => {
3 const { docViewer } = instance;
4 const document = instance.iframeWindow.document;
5
6 instance.UI.setHeaderItems(header => {
7 const parent = docViewer.getScrollViewElement().parentElement;
8
9 const menu = document.createElement('div');
10 menu.classList.add('Overlay');
11 menu.classList.add('FlyoutMenu');
12 menu.style.padding = '1em';
13
14 const downloadBtn = document.createElement('button');
15 downloadBtn.textContent = 'Download';
16 downloadBtn.onclick = () => {
17 // Download
18 };
19
20 menu.appendChild(downloadBtn);
21
22 let isMenuOpen = false;
23
24 const renderCustomMenu = () => {
25 const menuBtn = document.createElement('button');
26 menuBtn.textContent = 'My Menu';
27
28 menuBtn.onclick = () => {
29 if (isMenuOpen) {
30 parent.removeChild(menu);
31 } else {
32 menu.style.left = `${document.body.clientWidth - (menuBtn.clientWidth + 40)}px`;
33 menu.style.right = 'auto';
34 menu.style.top = '40px';
35 parent.appendChild(menu);
36 }
37
38 isMenuOpen = !isMenuOpen;
39 };
40
41 return menuBtn;
42 };
43
44 const newCustomElement = {
45 type: 'customElement',
46 render: renderCustomMenu,
47 };
48
49 header.push(newCustomElement);
50 });
51 });

Removing existing buttons

1WebViewer(...)
2 .then(instance => {
3 instance.UI.setHeaderItems(header => {
4 const items = header.getItems().slice(9, -3);
5 header.update(items);
6 });
7 });

Reordering annotation tool buttons

1WebViewer(...)
2 .then(instance => {
3 // remove the tools from existing group
4 instance.UI.updateTool('AnnotationCreateTextHighlight', { buttonGroup: '' });
5 instance.UI.updateTool('AnnotationCreateTextUnderline', { buttonGroup: '' });
6 instance.UI.updateTool('AnnotationCreateTextSquiggly', { buttonGroup: '' });
7 instance.UI.updateTool('AnnotationCreateTextStrikeout', { buttonGroup: '' });
8 // delete default tool buttons and add new ones in desired order
9 instance.UI.setHeaderItems(header => {
10 const items = header.getItems();
11 items.splice(10, 9,
12 {
13 type: 'toolButton',
14 toolName: 'AnnotationCreateTextStrikeout'
15 },
16 {
17 type: 'toolButton',
18 toolName: 'AnnotationCreateTextSquiggly'
19 },
20 {
21 type: 'toolButton',
22 toolName: 'AnnotationCreateTextUnderline'
23 },
24 {
25 type: 'toolButton',
26 toolName: 'AnnotationCreateTextHighlight'
27 }
28 );
29 header.update(items);
30 });
31 });

Appending logo and shifting existing buttons to the right

1WebViewer(...)
2 .then(instance => {
3 instance.UI.setHeaderItems(header => {
4 header.delete(9);
5 header.unshift({
6 type: 'customElement',
7 render: () => {
8 const logo = document.createElement('img');
9 logo.src = 'https://www.pdftron.com/downloads/logo.svg';
10 logo.style.width = '200px';
11 logo.style.marginLeft = '10px';
12 logo.style.cursor = 'pointer';
13 logo.onclick = () => {
14 window.open('https://www.pdftron.com', '_blank');
15 }
16 return logo;
17 }
18 }, {
19 type: 'spacer'
20 });
21 });
22 });

Relevant APIs

To add/remove/re-order header items, you can use the following API:

For ToolButton, make sure you register/unregister the tool using:

Did you find this helpful?

Trial setup questions?

Ask experts on Discord

Need other help?

Contact Support

Pricing or product questions?

Contact Sales