Customizing the Toolbar

PSPDFKit for Web comes with a customizable main toolbar that, by default, includes a number of predefined items. Thanks to a minimal and simple API, it is possible to customize the look and feel of built-in items, as well as alter the entire list of items or even add custom ones.

PSPDFKit.defaultToolbarItems

PSPDFKit is initialized with a default set of items which can be retrieved via PSPDFKit.defaultToolbarItems:

1
2
const defaultItems = PSPDFKit.defaultToolbarItems;
console.log(defaultItems);
1
2
var defaultItems = PSPDFKit.defaultToolbarItems;
console.log(defaultItems);

Items in the toolbar are plain JavaScript objects with the shape of a PSPDFKit.ToolbarItem.

The list of defaultToolbarItems can be used to prepare a custom toolbar before initialization:

Copy
1
2
3
4
5
const items = PSPDFKit.defaultToolbarItems;
// Reverse the item order.
items.reverse();
// Add a custom item at the end of the list.
items.push(aCustomItem);
Copy
1
2
3
4
5
var items = PSPDFKit.defaultToolbarItems;
// Reverse the item order.
items.reverse();
// Add a custom item at the end of the list.
items.push(aCustomItem);

Any valid array of PSPDFKit.ToolbarItem can then be set as toolbarItems when loading PSPDFKit:

1
2
3
PSPDFKit.load({
  toolbarItems: items
});
1
2
3
PSPDFKit.load({
  toolbarItems: items
});

Updating Toolbar Items

At any time, you can retrieve the current list of PSPDFKit.ToolbarItem with instance.toolbarItems:

Copy
1
2
3
4
5
const items = PSPDFKit.defaultToolbarItems;
// Reverse the item order.
items.reverse();
// Add a custom item at the end of the list.
items.push(aCustomItem);
Copy
1
2
3
4
5
var items = PSPDFKit.defaultToolbarItems;
// Reverse the item order.
items.reverse();
// Add a custom item at the end of the list.
items.push(aCustomItem);

instance.setToolbarItems

It is then possible to mutate the main toolbar with instance.setToolbarItems, which is a function that accepts an array of PSPDFKit.ToolbarItem:

1
instance.setToolbarItems(newItems);
1
instance.setToolbarItems(newItems);

This method can also be invoked with a function that gets the current toolbar items as arguments and must return the new list of items:

1
2
3
4
instance.setToolbarItems(items => {
  items.push(aCustomItem);
  return items;
});
1
2
3
4
instance.setToolbarItems(function(items) {
  items.push(aCustomItem);
  return items;
});

Custom Toolbar Items

As mentioned before, items in the toolbar are plain JavaScript objects with the shape of a PSPDFKit.ToolbarItem. Most of the time, they are buttons that perform an action upon being clicked.

The main differentiator between built-in toolbar items and user-defined ones is the type; for the former, it’s one of the PSPDFKit.defaultToolbarItems, and for the latter, it’s custom.

Optionally, custom items can also have an id to identify the item univocally:

1
2
3
4
5
6
7
8
const item = {
  type: "custom",
  id: "my-button",
  title: "My Button",
  onPress: event => {
    alert("hello from my button");
  }
};
Copy
1
2
3
4
5
6
7
8
var item = {
  type: "custom",
  id: "my-button",
  title: "My Button",
  onPress: function(event) {
    alert("hello from my button");
  }
};

When the icon for the item is missing, the title will be displayed instead. This is useful if you want to create text-only buttons.

onPress is a function that is invoked when the item is either clicked or tapped (on touch devices).

Once the custom button is ready, it is possible to insert it into the current list:

1
2
3
4
instance.setToolbarItems(items => {
  items.push(item);
  return items;
});
1
2
3
4
instance.setToolbarItems(function(items) {
  items.push(item);
  return items;
});

Customizing Built-In Items

It is possible to customize the following properties of built-in items:

  • title
  • icon
  • className
  • mediaQueries
  • disabled
  • preset

Please refer to the API documentation to learn more about each individual property:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Change the `mediaQueries` for the zoom items
// so that they are always shown on any device.

instance.setToolbarItems(items =>
  items.map(item => {
    if (
      item.type === "zoom-in" ||
      item.type === "zoom-out" ||
      item.type === "zoom-mode"
    ) {
      item.mediaQueries = ["all"];
    }
    return item;
  })
);
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Change the `mediaQueries` for the zoom items
// so that they are always shown on any device.

instance.setToolbarItems(function(items) {
  return items.map(function(item) {
    if (
      item.type === "zoom-in" ||
      item.type === "zoom-out" ||
      item.type === "zoom-mode"
    ) {
      item.mediaQueries = ["all"];
    }
    return item;
  });
});

Control Item Visibility via mediaQueries

Each PSPDFKit.ToolbarItem visibility is controlled by its mediaQueries property. When mediaQueries is not defined, the item will always be visible.

mediaQueries is an array of valid CSS media queries strings.

Additionally, built-in items have extra internal logic that, under some circumstances, removes them from the list. Please refer to the API documentation to learn more.

Toolbar Layout and the spacer Item

The items list is rendered as a flat list of sibling elements that are separated by a special toolbar item called spacer. This solution makes the toolbar layout very flexible and easy to customize.

The spacer is an empty element with flex: 1, and it pushes items from both sides together, making them more compact.

You can insert as many spacers as you want or create a custom toolbar spacer (item) to fit your needs.

Responsive Group

A responsive-group is special since it can be referenced by other toolbar items via the responsiveGroup property. When the media query of the group matches, all referenced toolbar items will be hidden, and the group’s icon will be shown instead. When it is clicked, it will expand into the referenced toolbar items.

A responsive-group can be used to group items on smaller screens, and you can easily see this responsive grouping behavior when you open PSPDFKit for Web on a mobile device. In the default UI, the annotate type of our built-in items is also a responsive group that is used to group all annotation tools on smaller screens. The result looks like this:

Whenever the mediaQueries of a responsive-group don’t match, the group icon will be hidden and the items will be inlined instead, like so:

To make a custom responsive-group, be sure to add a unique id to the group and set the responsiveGroup property of all referenced items to that ID:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const toolbarItems = [
  {
    type: "responsive-group",
    id: "my-group",
    mediaQueries: ["max-width..."],
    icon: "https://example.com/icon.png"
  },
  {
    type: "custom",
    id: "my-button-one",
    responsiveGroup: "my-group"
  },
  {
    type: "custom",
    id: "my-button-two",
    responsiveGroup: "my-group"
  }
];
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var toolbarItems = [
  {
    type: "responsive-group",
    id: "my-group",
    mediaQueries: ["max-width..."],
    icon: "https://example.com/icon.png"
  },
  {
    type: "custom",
    id: "my-button-one",
    responsiveGroup: "my-group"
  },
  {
    type: "custom",
    id: "my-button-two",
    responsiveGroup: "my-group"
  }
];

Dropdown Group

A dropdown group defines a common dropdown container for toolbar item buttons that share the same dropdownGroup property. When grouped together, all the toolbar items — except for the selected or default one — are hidden. However, they can be shown by opening the dropdown with the toggle arrow button.

PSPDFKit for Web includes some default dropdown groups for shapes and ink and for sidebar-related items.

You can modify or create a new dropdown group by assigning a unique name for the group to more than one ToolbarItem. This is done with the dropdownGroup property:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
const toolbarItems = [
  {
    type: "custom",
    title: "Button one",
    id: "my-button-one",
    dropdownGroup: "my-group",
    selected: true
  },
  {
    type: "custom",
    title: "Button two",
    id: "my-button-two",
    dropdownGroup: "my-group"
  },
  {
    type: "custom",
    title: "Button three",
    id: "my-button-three",
    dropdownGroup: "my-group"
  }
];
instance.setToolbarItems(items => items.concat(toolbarItems));
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
var toolbarItems = [
  {
    type: "custom",
    title: "Button one",
    id: "my-button-one",
    dropdownGroup: "my-group",
    selected: true
  },
  {
    type: "custom",
    title: "Button two",
    id: "my-button-two",
    dropdownGroup: "my-group"
  },
  {
    type: "custom",
    title: "Button three",
    id: "my-button-three",
    dropdownGroup: "my-group"
  }
];
instance.setToolbarItems(function(items) {
  return items.concat(toolbarItems);
});

Annotation Variant Buttons

Annotation variants are custom buttons with different properties than those of the default annotation buttons.

PSPDFKit for Web includes variants like ink-highlighter (PSPDFKit.Annotations#InkAnnotation) and arrow (PSPDFKit.Annotations#LineAnnotation).