Create a New Tool in Our Viewer Toolbar

Items in the toolbar are plain JavaScript objects with the shape of a PSPDFKit.ToolbarItem. Most of the time, they’re buttons that perform an action upon being clicked.

<a class=“pL pT pQ” href=”/getting-started/web/?frontend=vanillajs&download=npm&integration=global-variable>Try for Free Launch Demo

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 them univocally:

const item = {
  type: "custom",
  id: "my-button",
  title: "My Button",
  onPress: (event) => {
    alert("hello from my button");
  }
};

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

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

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

instance.setToolbarItems((items) => {
  items.push(item);
  return items;
});

Or, it can be passed to the list of toolbar items when loading the SDK:

PSPDFKit.load({
  toolbarItems: [...PSPDFKit.defaultToolbarItems, item]
});

Custom DOM Node

You can specify the node property and provide your own DOM node for the custom toolbar item you’re adding:

const selectNode = document.createElement("select");

selectNode.innerHTML = `
		<option value="alice">Alice</option>
		<option value="Bob">Bob</option>
		<option value="carol">Carol</option>
		<option value="john">John</option>
	`;

selectNode.addEventListener("change", (event) => {
  console.log(`Selected option: ${event.target.value}`);
});

const item = {
  type: "custom",
  id: "author",
  node: selectNode
};

instance.setToolbarItems((items) => [...items, item]);

Customizing Built-In Items

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

• title

• icon

• className

• mediaQueries

• disabled

• preset

Please see the API Reference to learn more about each individual property:

// Change the `mediaQueries` for the zoom items
// so that they're 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;
  })
);

Control Item Visibility via mediaQueries

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

mediaQueries is an array of valid CSS media query strings.

Additionally, built-in items have extra internal logic that, under some circumstances, removes them from the list. Please see the API Reference 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 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.