Popups

Popups are the floating context menus that appear over annotations, text selections, the content editor, and the crop-page tool. The WebViewer exposes four popup properties, each implementing the UI.Popup interface so you can read, add, and replace their action items.

The UI.Popup interface

All four popup properties are built by api_helpers/createPopupAPI.js. Each implements:

Method	Signature	Purpose
add(items, dataElement?)	(items: Array|object, dataElement?: string) => this	Insert items after the item with the given dataElement (or at the beginning if omitted). Non-arrays are wrapped.
update(items?)	(items?: Array|object) => this	Replace all popup items (clears if undefined).
getItems()	() => Array<object>	Return the current popup items.

To remove items, use UI.disableElements with the item's dataElement.

The four popups

UI.textPopup

Popup for the text-selection context menu.

/**
 * @name UI.textPopup
 * @implements {UI.Popup}
 * @type {UI.Popup}
 */
UI.textPopup.getItems();        // => [{ type, dataElement, ... }, ...]

Default actions: copy, highlight, underline, strikeout, squiggly.

UI.annotationPopup

Popup for selected annotations.

/**
 * @name UI.annotationPopup
 * @implements {UI.Popup}
 * @type {UI.Popup}
 */

Default actions vary by annotation type: reply, copy, property, settings, delete. Link and erasure-redaction annotations show delete only; redaction shows property + delete; form fields show property/copy/delete.

UI.contentEditorPopup

Popup for the content editor.

/**
 * @name UI.contentEditorPopup
 * @implements {UI.Popup}
 * @type {UI.Popup}
 */

Default actions: copy, delete, property.

UI.cropPagePopup

Popup for the crop-page component.

/**
 * @name UI.cropPagePopup
 * @implements {UI.Popup}
 * @type {UI.Popup}
 */

Default actions: crop, close/exit.

Item structure

Popup items share the same descriptor shape as toolbar items — type (actionButton, statefulButton, toggleElementButton, toolButton), dataElement, icon, label, and onClick. The popup components (components/Popups/) render items via CustomButton and typed Button branches, filtering out items whose dataElement is disabled.

Positioning

Popup position is computed by helpers/getPopupPosition.js — getAnnotationPopupPositionBasedOn(rect, pageNumber, popup, documentViewerKey=1, position='right') returns { left, top }. It converts page-space annotation corners to window coordinates via core.pageToWindow, then clamps the popup within the scroll container's viewport (preferring below the annotation, falling back to above or to the side with more space).

Examples

Add a custom action to the annotation popup

UI.annotationPopup.add({
  type: 'actionButton',
  dataElement: 'myAnnotAction',
  label: 'Send to backend',
  onClick: () => { /* … */ },
});

Replace the text-popup actions

UI.textPopup.update([
  { type: 'actionButton', dataElement: 'copyTextButton',  label: 'Copy' },
  { type: 'toolButton',   dataElement: 'highlightToolButton', label: 'Highlight' },
]);

Remove an item

UI.disableElements(['replyButton']);   // removes the reply action from the annotation popup

Internal notes

• Popup item arrays live in the viewer store (textPopup[], annotationPopup[], contentEditorPopup[], cropPagePopup[]) and are accessed through the encapsulated viewerStore.dispatch('getPopupItems')(popupDataElement).
• The popup components read items via useViewer.getPopupItems(<key>) and filter by isElementDisabled.
• showAnnotationPopup / popoverChanged flags in the store control popup visibility timing.

Related

• Show / Hide Elements — removing popup items.
• Components — the Popups/ component tree.
• API Reference