Get Started

play_arrow

Learn more

play_arrow

Common use cases

play_arrow

Open a document

play_arrow

Save a document

play_arrow

Viewer

play_arrow

UI Customization

play_arrow

Annotations

play_arrow

Collaboration

play_arrow

Forms

play_arrow

Signature

play_arrow

Measurement

play_arrow

PDF.js Express REST API

play_arrow

Customize toolbar in viewer

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

The PDF.js Express Web Viewer UI provides a flexible API to easily handle each of these cases and more.

To learn about 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

The header is represented by an array of header items and you can edit the array to add/remove/reorder them however you want. The API, setHeaderItems, will provide a header object as a function argument.

Header and json

For cases where the user wants to replace the entire header items back and forth, the header items are grouped, and displayed only when the group is active:

Header groups and json

Header items

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

var newActionButton = {
  type: 'actionButton',
  img: 'path/to/image',
  onClick: function() {
    alert('Hello world!');
  },
  dataElement: 'alertButton',
  hidden: [ 'mobile' ]
};

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

var countButton = {
  type: 'statefulButton',
  initialState: 'Count',
  states: {
    Count: {
      number: 1,
      getContent: function(activeState) {
        return activeState.number;
      },
      onClick: function(update, activeState) {
        activeState.number += 1;
        update();
      }
    }
  },
  dataElement: 'countButton'
};

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.

var nextPageButton = {
  type: 'statefulButton',
  initialState: 'Page',
  states: {
    Page: {
      getContent: function() {
        return instance.getCurrentPageNumber();
      },
      onClick: function() {
        var currentPage = instance.getCurrentPageNumber();
        var totalPages = instance.getPageCount();
        var atLastPage = currentPage === totalPages;

        if (atLastPage) {
          instance.goToFirstPage();
        } else {
          instance.goToNextPage();
        }
      }
    }
  },
  mount: function(update) {
    instance.docViewer.on('pageNumberUpdated.nextPageButton', function() {
      // We want to update this button when page number changes so it can have the correct content;
      update();
    });
  },
  unmount: function() {
    instance.docViewer.off('pageNumberUpdated.nextPageButton')
  },
  dataElement: 'nextPageButton'
};

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

This button is in our built-in UI, checkout it out in the demo.

Stateful Fitmode Button

var fitButton = {
  type: 'statefulButton',
  initialState: 'FitWidth',
  states: {
    FitWidth: {
      img: 'path/to/fitWidth/image',
      onClick: function() {
        instance.setFitMode(instance.FitMode.FitWidth);
      },
    },
    FitPage: {
      img: 'path/to/fitPage/image',
      onClick: function() {
        instance.setFitMode(instance.FitMode.FitPage);
      },
    }
  },
  mount: function(update) {
    function fitModeToState(fitMode) {
      // the returned state should be the opposite of the new current state
      // as the opposite state is what we want to switch to when the button
      // is clicked next
      if (fitMode === instance.docViewer.FitMode.FitPage) {
        return 'FitWidth';
      } else if (fitMode === instance.docViewer.FitMode.FitWidth) {
        return 'FitPage';
      }
    };

    instance.docViewer.on('fitModeUpdated.fitbutton', function(fitMode) {
      update(fitModeToState(fitMode));
    });
  },
  unmount: function() {
    instance.docViewer.off('fitModeUpdated.fitbutton');
  },
  dataElement: 'fitButton',
  hidden: ['mobile']
};

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

var newToggleElementButton = {
  type: 'toggleElementButton',
  img: 'path/to/image',
  element: 'leftPanel',
  dataElement: 'leftPanelButton',
  hidden: [ 'mobile' ]
};

ToolButton

ToolButton activates a PDF.js Express Web Viewer 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

var newToolButton = {
  type: 'toolButton',
  toolName: 'AnnotationCreateFreeText',
  hidden: [ 'mobile' ]
}

ToolGroupButton

ToolGroupButton opens an overlay with the tools in the 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.

Tool group button

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

var newToolGroupButton = {
  type: 'toolGroupButton',
  toolGroup: 'shapeTools',
  dataElement: 'shapeToolGroupButton',
  hidden: [ 'mobile' ]
};

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

var renderSlider = function() {
  var slider = document.createElement('input');
  slider.type = 'range';
  slider.oninput = function() {
    // Do something
  };

  return slider;
}

var newCustomElement = {
  type: 'customElement',
  render: renderSlider
};

In React jsx:

const Slider = () => {
  return (
    <input
      type="range"
      onInput={() => { /* Do something */ }}
    >
    </input>
  );
}

const newCustomElement = {
  type: 'customElement',
  render: () => <Slider />
};

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

var newSpacer = {
  type: 'spacer',
  hidden: [ 'mobile' ]
};

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

var newDivider = {
  type: 'divider',
  hidden: [ 'mobile' ]
};

Examples

Add a custom save button

WebViewer(...)
  .then(function(instance) {
    instance.setHeaderItems(function(header) {
      header.push({
        type: 'actionButton',
        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>',
        onClick: function() {
          // save the annotations
        }
      });
    });
  });

Remove existing buttons

WebViewer(...)
  .then(function(instance) {
    instance.setHeaderItems(function(header) {
      var items = header.getItems().slice(9, -3);
      header.update(items);
    });
  });

Reorder annotation tool buttons

var viewerElement = document.getElementById('viewer');
var viewer = new PDFTron.WebViewer({ ... }, viewerElement);

viewerElement.addEventListener('ready', function() {
  var viewerInstance = viewer.getInstance();
  // remove the tools from existing group
  viewerInstance.updateTool('AnnotationCreateTextHighlight', { group: '' });
  viewerInstance.updateTool('AnnotationCreateTextUnderline', { group: '' });
  viewerInstance.updateTool('AnnotationCreateTextSquiggly', { group: '' });
  viewerInstance.updateTool('AnnotationCreateTextStrikeout', { group: '' });
  // delete default tool buttons and add new ones in desired order
  viewerInstance.setHeaderItems(function(header) {
    var items = header.getItems();
    items.splice(10, 9,
      {
        type: 'toolButton',
        toolName: 'AnnotationCreateTextStrikeout'
      },
      {
        type: 'toolButton',
        toolName: 'AnnotationCreateTextSquiggly'
      },
      {
        type: 'toolButton',
        toolName: 'AnnotationCreateTextUnderline'
      },
      {
        type: 'toolButton',
        toolName: 'AnnotationCreateTextHighlight'
      }
    );
    header.update(items);
  });
});

Append logo and shifting existing buttons to the right

WebViewer(...)
  .then(function(instance) {
    instance.setHeaderItems(function(header) {
      header.delete(9);
      header.unshift({
        type: 'customElement',
        render: function() {
          var logo = document.createElement('img');
          logo.src = 'https://www.pdftron.com/downloads/logo.svg';
          logo.style.width = '200px';
          logo.style.marginLeft = '10px';
          logo.style.cursor = 'pointer';
          logo.onclick = function() {
            window.open('https://www.pdftron.com', '_blank');
          }
          return logo;
        }
      }, {
        type: 'spacer'
      });
    });
  });

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:

To switch a header group, you can use the following API: