Interface: ToolbarItem

PSPDFKit.ToolbarItem

Describes the properties of a Toolbar Item.

Check out our guides for more examples.

Extends

Members



Members

(nullable) className: string

Useful to set a custom CSS class name on the item.

For default items theclassName is appended to the default item ones.

Type:
  • string

(nullable) disabled: boolean

Whether the item is disabled or not.

The property can be used to force a default item to be disabled by setting it to true.

Type:
  • boolean

Can be used to group multiple toolbar buttons in the same PSPDFKit.ToolbarItem#dropdownGroup. Only one of the buttons will be visible, with a dropdown arrow to hint the user about the dropdown group. When the user clicks on the arrow, the rest of the buttons will be shown vertically piled.

The toolbar buttons that belong to a dropdown group will preserve all the properties of individual toolbar buttons.

In order to decide which toolbar item is visible, the following criteria is used:

  • If a button is globally selected, it's rendered on top.
  • Otherwise, the last globally selected button of the list is rendered on top.
  • If none of those has been selected before, the first button on the dropdown group is rendered on top.

Note: It is not possible to override this option for built-in toolbar items.

Type:
  • string
Example
const toolbarItems = [
  {
    type: "responsive-group",
    id: "my-group",
    mediaQueries: ["(min-width: 980px)"],
    icon: "https://example.com/icon.png",
  },
  {
    type: "custom",
    id: "my-button-one",
    responsiveGroup: "my-group",
    dropdownGroup: "my-dropdown-group",
  },
  {
    type: "custom",
    id: "my-button-two",
    dropdownGroup: "my-dropdown-group",
  },
];

(nullable) icon: string

Icon for the item.

The icon should either be an URL, a base64 encoded image or the HTML for an inline SVG. This property can override the default items' ones.

Type:
  • string

(nullable) id: string

Unique identifier for the item.

This is useful to identify items whose type is custom.

Type:
  • string
Example
// In your JavaScript
const documentEditorToolbarItems = PSPDFKit.defaultDocumentEditorToolbarItems
documentEditorToolbarItems.push({ type: 'custom', id: 'my-button', ... })
PSPDFKit.load({
 ...otherOptions,
 documentEditorToolbarItems
});

Note: It is ***not*** possible to override this option for built-in document editor toolbar items.

(nullable) id: string

Unique identifier for the item.

This is useful to identify items whose type is custom.

Type:
  • string
Example
// In your JavaScript
const toolbarItems = PSPDFKit.defaultTextComparisonToolbarItems
toolbarItems.push({ type: 'custom', id: 'my-button', ... })
PSPDFKit.loadTextComparison({
 ...otherOptions,
 toolbarItems
});

Note: It is ***not*** possible to override this option for built-in text comparison toolbar items.

(nullable) id: string

Unique identifier for the item.

This is useful to identify items whose type is custom or responsive-group.

Type:
  • string
Example
// In your JavaScript
const toolbarItems = PSPDFKit.defaultToolbarItems
toolbarItems.push({ type: 'custom', id: 'my-button', ... })
PSPDFKit.load({
  ...otherOptions,
  toolbarItems
});

Note: It is ***not*** possible to override this option for built-in toolbar items.

(nullable) mediaQueries: Array.<string>

An array of valid media queries which are used to determine the visibility of an item.

Internally media queries are managed using the Window.matchMedia() API.

As per the W3C Spec in many cases media queries require parenthesis for example min-width: 480px won't work whereas (min-width: 480px) will.

Type:
  • Array.<string>
Example

Overwrite the default media query for the zoom-in default button.

const toolbarItems = PSPDFKit.defaultToolbarItems;
const index = toolbarItems.findIndex(item => item.type === "zoom-in");
toolbarItems[index]["mediaQueries"] = ["(min-width: 1000px)"];
instance.setToolbarItems(toolbarItems);

(nullable) node: Node

Optionally custom tool items can define a DOM node. PSPDFKit renders this node instead of a standard tool button.

In this case the tool item is rendered inside of a container which gets the title and className attributes set.

The icon property is ignored. The selected and disabled are used just to toggle the PSPDFKit-Tool-Node-active and PSPDFKit-Tool-Node-disabled class names but making the node effectively selected or disabled is up to the implementation of the item.

The onPress event is registered and fires any time the item is either clicked or selected with keyboard (if part of a dropdownGroup).

Type:
  • Node
Inherited From:

(nullable) onPress: function

Callback to invoke when the item is clicked or tapped (on touch devices). It gets the event as first argument, the id of the tool item as the second.

Type:
  • function
Inherited From:

(nullable) preset: string

Annotation preset for annotations. It will be passed to the onPress event handler in the third argument.

Type:
  • string

(nullable) responsiveGroup: string

Can be used to link multiple toolbar items to the same responsive-group. Those items will be hidden when the responsive group icon is displayed and can be seen when we click (i.e. open) the group.

Whenever a toolbar item is active and it's responsive group is shown, the responsive group is open so the active state can be seen.

Note: It is not possible to override this option for built-in toolbar items.

Type:
  • string
Example
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",
  },
];

(nullable) selected: boolean

Whether a custom item is selected or not.

The selected status of default items cannot be altered.

Note: It is not possible to override this option for built-in toolbar items.

Type:
  • boolean

(nullable) title: string

Title for the tool items.

It is shown on hover or when the item doesn't have an icon.

Type:
  • string
Inherited From:

type: string

required

The type of a toolbar item.

It can either be custom for user defined items, responsive-group to combine items on smaller screens, or one from the PSPDFKit.defaultToolbarItems.

Special types:

  • responsive-group (and annotate as a predefined responsive group): These types can be referenced by other toolbar items via the PSPDFKit.ToolbarItem#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.

Note: It is not possible to override this option for built-in toolbar items.

Type:
  • string
Example
// In your JavaScript
const toolbarItems = PSPDFKit.defaultToolbarItems
toolbarItems.push({ type: 'custom', ... })
PSPDFKit.load({
  ...otherOptions,
  toolbarItems
});

See also