---
title: "Create new annotation tool in JavaScript PDF viewer | Nutrient"
canonical_url: "https://www.nutrient.io/guides/web/user-interface/annotation-toolbar/create-a-new-tool/"
md_url: "https://www.nutrient.io/guides/web/user-interface/annotation-toolbar/create-a-new-tool.md"
last_updated: "2026-05-30T02:20:01.425Z"
description: "Learn how to create custom toolbar items in Nutrient using JavaScript. Discover the key properties and see a demo to enhance your PDF annotation tools."
---

# Create a new annotation tool in our viewer toolbar

Items in the toolbar are plain JavaScript objects with the shape of a [`NutrientViewer.AnnotationToolbarItem`](https://www.nutrient.io/api/web/NutrientViewer.AnnotationToolbarItem.html). Most of the time, they’re buttons that perform an action upon being clicked.

Looking to build the annotation 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.contextual` [slot](https://www.nutrient.io/guides/web/user-interface/ui-customization/supported-slots.md#tools), which renders the contextual toolbar that appears when an annotation is selected or a mode is active. The annotation 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/annotations/)

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

The `custom` items should have an `id` property, which is used to identify the item in the toolbar. Also, you have to specify the [`node` property](https://www.nutrient.io/api/web/NutrientViewer.AnnotationToolbarItem.html) and provide your own DOM node for the custom toolbar item you’re adding:

```js

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: "my-button",
  node: selectNode,
  onPress: (event) => {
    alert("hello from my button");
  }
};

```

`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.setAnnotationToolbarItems(
  (annotation, { defaultAnnotationToolbarItems }) => {
    return [...defaultAnnotationToolbarItems, item];
  }
);

```

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

```js

NutrientViewer.load({
  annotationToolbarItems: (
    annotation,
    { defaultAnnotationToolbarItems }
  ) => {
    return [...defaultAnnotationToolbarItems, item];
  }
});

```

## 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` that can be used to add space in between or around the toolbar items.

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

## Related pages

- [Customizing an existing annotation tool in our viewer toolbar](/guides/web/user-interface/annotation-toolbar/customize-existing-tools.md)
- [Creating a custom annotation toolbar for mobile devices](/guides/web/user-interface/annotation-toolbar/mobile-responsiveness.md)
- [Rearranging annotation tools in our viewer toolbar](/guides/web/user-interface/annotation-toolbar/rearrange.md)
- [Removing an annotation tool from our viewer toolbar](/guides/web/user-interface/annotation-toolbar/remove-a-tool.md)