Header & Toolbar

The header is the top bar of the viewer. It contains the main toolbar (default group), the toolbar-group switcher (Ribbons), a secondary contextual toolbar (ToolsHeader), and several mode-specific bars (form board, signature verify bar, security apply bar). This guide explains the structure and the APIs for customizing it.

UI APIs

UI.setHeaderItems(headerCallback)

Customize the header / toolbar groups by mutating a Header helper object inside a callback.

/**
 * @method UI.setHeaderItems
 * @param {UI.headerCallback} headerCallback Callback that operates on a {UI.Header} instance.
 */
UI.setHeaderItems(header => {
  header.getHeader('default')         // select a group to edit
    .push({ type: 'actionButton', dataElement: 'myBtn', /* … */ });
});

The callback receives a UI.Header instance — a mutable working copy of all header arrays. After the callback returns, each mutated group is written back into the viewer store, which reactively re-renders the toolbar.

UI.Header — chainable DSL

Method	Signature	Purpose
get(dataElement)	(dataElement: string) => Header	Select a button by data-element for subsequent insertBefore / insertAfter / delete.
getItems()	() => Array<object>	Return the current group's item list.
getHeader(group)	(group: string) => Header	Switch the active group being edited.
insertBefore(item)	(item: object) => Header	Insert before the selected button.
insertAfter(item)	(item: object) => Header	Insert after the selected button.
delete(id?)	(id?: number|string|Array) => Header	Delete by index, data-element, the currently-selected button (no arg), or an array.
shift()	() => Header	Remove the first button.
unshift(...items)	(...items) => Header	Prepend button(s).
push(...items)	(...items) => Header	Append button(s).
pop()	() => Header	Remove the last button.
update(items)	(items: Array<object>) => Header	Replace the entire group's item list.

UI.setToolbarGroup(group)

Switch the active toolbar group.

/**
 * @method UI.setToolbarGroup
 * @param {string} groupDataElement One of:
 *   toolbarGroup-View, toolbarGroup-Annotation, toolbarGroup-Form,
 *   toolbarGroup-Measurement, toolbarGroup-Sign, toolbarGroup-Security,
 *   toolbarGroup-Redaction, toolbarGroup-Compare, toolbarGroup-Editor,
 *   toolbarGroup-Document, toolbarGroup-Separation
 */
UI.setToolbarGroup('toolbarGroup-Annotation');

Internally it sets the active toolbar group, the active header group, and the active tool mode. The legacy toolMenu-* names are accepted with a deprecation warning and mapped to toolbarGroup-*.

UI.setActiveToolMode and UI.setActiceToolMode (typo) are deprecated aliases for setToolbarGroup and emit a [ComPDF] "..." is deprecated... warning.

Toolbar structure

Header groups

The headers state in the viewer store is a map of group name → item-array. The main groups:

Group	Contents
default	Main top header: left-panel toggle, fullscreen, hand tool, zoom overlay, crop page, Ribbons (group switcher), search, etc.
small-mobile-more-buttons	Overflow buttons on small mobile screens.
toolbarGroup-View	View tools.
toolbarGroup-Annotation	Annotation tools.
toolbarGroup-Form	Form-field creation tools.
toolbarGroup-Measurement	Measurement tools.
toolbarGroup-Sign	Signature tools.
toolbarGroup-Security	Security / encryption tools.
toolbarGroup-Redaction	Redaction & remove tools.
toolbarGroup-Compare	Document-compare tools.
toolbarGroup-Editor	Content-editor tools.
toolbarGroup-Document	Page-editor tools.
toolbarGroup-Separation	Color-separation tools.

Related state: rightHeaders (open-file, search, page-mode, download, flatten, print, theme, settings), toolItems (security/redaction sub-items), documentEditorHeaders.

Item types

Each item descriptor has a type field dispatched by the HeaderItems.vue renderer:

type	Renders as
toolButton	<ToolButton> — activates a tool.
actionButton	<ActionButton> — runs onClick.
toggleElementButton	<ToggleElementButton> — opens/closes an element.
statefulButton	<StatefulButton> — button with on/off state.
customElement	A component looked up in componentMap (Ribbons, ZoomOverlay, LeftPanelButton, Dropdown, SignatureToolBar, SecurityToolbar, RedactionToolbar, ComparedToolbar, FillForm, SelectToolsButton), or a generic <CustomElement> for user-supplied render functions.
divider / spacer	Empty flex <div> separators.

Secondary bars

• Ribbons (components/Ribbons/) — the toolbar-group switcher rendered inside the default header. Lists enabled toolbarGroup-* data-elements, marks the active one, and collapses overflow into a "···" menu.
• ToolsHeader (components/ToolsHeader/) — a secondary toolbar row below the main header. Renders the items for the active toolbarGroup-* via getToolbarGroupItems(currentToolbarGroup). Hidden for view/document/separation/unfinished-compare modes.
• FormBoard, SignatureVerifyBar, SecurityApplyBar — mode-specific bars rendered conditionally by Header.vue.

How setHeaderItems works internally

apis/setHeaderItems.js builds a Header object via Object.create(Header).initialize(store, headerGroups) — a working copy of headers, rightHeaders, tools, toolItems, and documentEditorHeaders. The user callback mutates this copy. After it returns, the API writes each working-copy array back into store.headers[group], triggering reactive re-render of HeaderItems.vue.

HeaderItems.vue computes visibleItems (hides items by mobile/PC flags and isElementDisabled) and applies responsive hide classes (hide-in-desktop, hide-in-tablet, hide-in-mobile, hide-in-small-mobile, always-hide). On mount it wires createHeaderItemsListener, which keeps toolbar buttons in sync with selection/tool state (disabling the property-panel buttons when nothing relevant is selected).

Examples

Remove a button by data-element

UI.setHeaderItems(header => {
  header.getHeader('default').delete('downloadButton');
});

Insert a custom button before an existing one

UI.setHeaderItems(header => {
  header.getHeader('default')
    .get('printButton')
    .insertBefore({
      type: 'actionButton',
      dataElement: 'myAction',
      label: 'My Action',
      onClick: () => console.log('clicked'),
    });
});

Replace an entire group's items

UI.setHeaderItems(header => {
  header.getHeader('toolbarGroup-View').update([
    { type: 'toolButton', dataElement: 'handToolButton', /* … */ },
    { type: 'toolButton', dataElement: 'zoomOverlayButton', /* … */ },
  ]);
});

Add a right-side header button

Right-side buttons live in the rightHeaders array. You can push to it the same way after selecting it; note getHeader accepts the group key — for the right header use the appropriate group, or manipulate rightHeaders via the store if exposed.

Related

• Show / Hide Elements — disableElements to hide buttons without restructuring the toolbar.
• Components — the internal Header / HeaderItems component tree.
• API Reference — full setHeaderItems / setToolbarGroup signatures.