Describes the properties of a Toolbar Item.
Check out our guides for more examples.
Extends
Members
Members
Useful to set a custom CSS class name on the item.
For default items theclassName
is appended to the default item ones.
Type:
- string
- Overrides:
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
- Overrides:
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",
},
];
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
- Overrides:
Unique identifier for the item.
This is useful to identify items whose type
is
custom
.
Type:
- string
- Overrides:
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.
Unique identifier for the item.
This is useful to identify items whose type
is
custom
or responsive-group
.
Type:
- string
- Overrides:
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.
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
const toolbarItems = PSPDFKit.defaultToolbarItems;
const index = toolbarItems.findIndex(item => item.type === "zoom-in");
toolbarItems[index]["mediaQueries"] = ["(min-width: 1000px)"];
instance.setToolbarItems(toolbarItems);
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:
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:
Annotation preset for annotations. It will be passed to the
onPress
event handler in the third argument.
Type:
- 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",
},
];
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
- Overrides:
Title for the tool items.
It is shown on hover or when the item doesn't have an icon.
Type:
- string
- Inherited From:
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
(andannotate
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
- Overrides:
Example
// In your JavaScript
const toolbarItems = PSPDFKit.defaultToolbarItems
toolbarItems.push({ type: 'custom', ... })
PSPDFKit.load({
...otherOptions,
toolbarItems
});