---
title: "Create a new tool in JavaScript PDF viewer toolbar | Nutrient Web SDK"
canonical_url: "https://www.nutrient.io/guides/web/user-interface/main-toolbar/create-a-new-tool/"
md_url: "https://www.nutrient.io/guides/web/user-interface/main-toolbar/create-a-new-tool.md"
last_updated: "2026-05-25T14:09:00.402Z"
description: "Learn how to create a new tool in the viewer toolbar using Nutrient Web SDK. Extend the functionality of your PDF viewer with custom actions and user interface elements."
---
# Create a new tool in PDF viewer toolbar
Items in the toolbar are plain JavaScript objects with the shape of a [`NutrientViewer.ToolbarItem`](https://www.nutrient.io/api/web/NutrientViewer.ToolbarItem.html). Most of the time, they’re buttons that perform an action upon being clicked.
Looking to build the toolbar from scratch instead of adding to ours? See [building headless document UIs](https://www.nutrient.io/guides/web/user-interface/ui-customization/headless-ui.md) and the `tools.main` [slot](https://www.nutrient.io/guides/web/user-interface/ui-customization/supported-slots.md#tools). The toolbar items API on this page is still the right tool when you want to keep our toolbar chrome and add buttons to it.
[Try for Free](https://www.nutrient.io/sdk/web/getting-started.md)
[Launch Demo](https://www.nutrient.io/demo/toolbar-customization)
The main differentiator between built-in toolbar items and user-defined ones is the `type`; for the former, it’s one of the [`NutrientViewer.defaultToolbarItems`](https://www.nutrient.io/api/web/modules/NutrientViewer.html#.defaultToolbarItems), and for the latter, it’s `custom`.
Optionally, `custom` items can also have an `id` to identify them univocally:
```js
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:
```js
instance.setToolbarItems((items) => {
items.push(item);
return items;
});
```
Or, it can be passed to the list of toolbar items when loading the SDK:
```js
NutrientViewer.load({
toolbarItems: [...NutrientViewer.defaultToolbarItems, item]
});
```
### Custom DOM node
You can specify the [`node` property](https://www.nutrient.io/api/web/NutrientViewer.ToolItem.html#node) and provide your own DOM node for the custom toolbar item you’re adding:
```js
const selectNode = document.createElement("select");
selectNode.innerHTML = `
`;
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`
See the [API reference](https://www.nutrient.io/api/web/) to learn more about each individual property:
```js
// 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 through mediaQueries
Each [`NutrientViewer.ToolbarItem`](https://www.nutrient.io/api/web/NutrientViewer.ToolbarItem.html) 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](https://www.nutrient.io/api/web/NutrientViewer.ToolbarItem.html#mediaQueries) strings.
Additionally, built-in items have extra internal logic that, under some circumstances, removes them from the list. See the [API reference](https://www.nutrient.io/api/web/) to learn more.
## Toolbar layout and the spacer item
The items list is rendered as a flat list of sibling elements separated by a special toolbar item called `spacer`. This solution enables you to modify and rearrange the toolbar layout to suit your requirements.
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 `spacer`s as you want, or create a custom toolbar spacer (item) to fit your needs.
---
## Related pages
- [Activate or deactivate tools in our viewer toolbar](/guides/web/customizing-the-interface/controlling-the-toolbar-via-api.md)
- [Configuring pager toolbar display behavior](/guides/web/user-interface/main-toolbar/pager-display.md)
- [Customizing download/export buttons in our JavaScript PDF viewer](/guides/web/user-interface/main-toolbar/download-export-button.md)
- [Customizing tools in the JavaScript PDF viewer toolbar](/guides/web/user-interface/main-toolbar/customize-existing-tools.md)
- [Customize dropdown navigation in the viewer toolbar](/guides/web/user-interface/main-toolbar/dropdown-groups.md)
- [Hiding the toolbar in our JavaScript PDF viewer](/guides/web/user-interface/main-toolbar/hide-the-toolbar.md)
- [Adjust the placement of the toolbar in our viewer](/guides/web/user-interface/main-toolbar/placement.md)
- [Adding page labels to navigation in our viewer](/guides/web/features/navigation-page-labels.md)
- [Customize the print button (hide/enable) in our JavaScript PDF viewer](/guides/web/user-interface/main-toolbar/print-button.md)
- [Rearrange tools in our viewer toolbar](/guides/web/user-interface/main-toolbar/rearrange.md)
- [Customizing responsive navigation in our viewer toolbar](/guides/web/user-interface/main-toolbar/responsive-groups.md)
- [Removing a tool from the toolbar in our JavaScript viewer](/guides/web/customizing-the-interface/customizing-the-toolbar.md)