Toolbars

In the Review Interface, the toolbar contains the buttons and icons that users click to perform actions in the document viewer. For example, the Review Interface contains a toolbar with page navigation, redaction, and zoom buttons.

The viewer configuration determines whether the Review Interface has multiple or no toolbars displayed. You can customize this configuration using the Review API or extension scripts.

This page contains the following information:

• Create toolbar controls using the Review API
• Create toolbar controls in extension scripts

Create toolbar controls using the Review API

You can use the Review Interface API (IReviewInterfaceApi) to create toolbar controls with IToolbarService. You can access this service via IReviewInterfaceApi.toolbar.

To create a toolbar control, use the IToolbarService.createToolbarControl function. It takes an argument of type IToolbarControlConfig.

The following code sample illustrates how to perform these tasks:

• Retrieve the viewer toolbar object by calling IToolbarService.getToolbarById.

• Create a toolbar control by calling IToolbarService.createToolbarControl.

• Add the control to the viewer toolbar by calling IToolbar.addControl and pass the new button control object.

reviewapi.on("apiready", function () {
  // Get all the loaded toolbars in the Review Interface.
  var allToolbars = reviewapi.toolbar.allToolbars;

  // Get the required toolbar by its ID.
  var viewerToolbar = reviewapi.toolbar.getToolbarById("ri-viewer-toolbar");

  // Create a toolbar control.
  var buttonControl = reviewapi.toolbar.createToolbarControl({
    type: "button",
    id: "testButton1",
    title: "Test Button",
    class: "testClass",
    onClick: function () {
      alert("Toolbar Button Clicked!");
    },
    imageUrl: "https://wwww.gstatic.com/webp/gallery3/2.png",
  });

  // Add a button control to the view toolbar.
  viewerToolbar.addControl(buttonControl, "left");
});

Create toolbar controls in extension scripts

You can also create toolbar controls as part of a Review Extensions script file. Use the IExtensionConfig.viewerToolbarControls function to add toolbar controls to all viewer types (ViewerType) or to a specific type.

The viewerToolbarControls function receives:

• api (IReviewInterfaceApi) — the Review Interface API
• viewerType (ViewerType) — the viewer type this toolbar belongs to
• viewerToolbar (IToolbar) — the toolbar instance to add controls to
• viewerCollection — the viewer collection

The function must return Promise<void>. Use await viewerToolbar.createToolbarControl(config, alignment) to create and add a control in a single call.

Resolving image URLs for CDN-delivered extensions

For button type controls, imageUrl must be a fully-resolved URL. If the image is co-deployed to the same CDN folder as the extension entry point, use parameters.getResourceUrl(fileName) to resolve it:

export default function(parameters: IExtensionParameters) {
  const iconUrl = parameters.getResourceUrl('review.myextension.icon.png');

  return {
    // ...
    viewerToolbarControls: async (_api, _viewerType, viewerToolbar) => {
      await viewerToolbar.createToolbarControl(
        { type: 'button', id: 'myextension-button', title: 'My Button', class: '', imageUrl: iconUrl, onClick: () => {} },
        'right' as unknown as ToolbarControlAlignment,
      );
    },
  };
}

parameters.getResourceUrl(fileName) resolves fileName relative to the CDN folder where the extension entry point JS lives. The image file must be co-deployed to that same folder. For RAP-delivered extensions, use parameters.getResourceFileUrl(fileName) instead — see IExtensionParameters.extensionDetails.source to detect which is active.

Note:rwcbutton is preferred for modern CDN extensions since it uses RWC icon names and requires no separate asset deployment.

Control types

TypeScript example (recommended: rwcbutton)

import type { IReviewInterfaceApi, IToolbar, IToolbarRWCButtonControlConfig, ToolbarControlType, ToolbarControlAlignment } from 'reviewapi';

viewerToolbarControls: async (_api: IReviewInterfaceApi, _viewerType: string, viewerToolbar: IToolbar): Promise<void> => {
  await viewerToolbar.createToolbarControl(
    {
      type: 'rwcbutton' as unknown as ToolbarControlType,
      id: 'myextension-button',
      title: 'My Button',
      class: '',
      wrapperClass: '',
      theme: '',
      icon: 'search', // RWC icon name — see relativity-web-components for available icons
      onClick: () => { /* handle click */ },
    } as unknown as IToolbarRWCButtonControlConfig,
    'right' as unknown as ToolbarControlAlignment,
  );
},

TypeScript note:ToolbarControlType, ToolbarControlAlignment are declare enum types — they have no JavaScript runtime representation and cannot be imported as values. Use string literals cast with as unknown as EnumType.

RWC icon names used by RI's own toolbar buttons include: "search", "text-wrap", "highlights-previous", "highlights-next", "cells-show-hidden", "history", "message". See relativity-web-components for the full list.

Toggle button example (rwctogglebutton)

import type { IToolbarRWCToggleControlConfig } from 'reviewapi';

await viewerToolbar.createToolbarControl(
  {
    type: 'rwctogglebutton' as unknown as ToolbarControlType,
    id: 'myextension-toggle',
    title: 'Toggle Feature',
    class: '',
    wrapperClass: '',
    theme: '',
    active: false,
    icon: 'text-wrap',          // icon when inactive
    activeIcon: 'text-wrap',    // icon when active (can differ)
    onClick: (active: boolean) => { /* handle toggle */ },
  } as unknown as IToolbarRWCToggleControlConfig,
  'right' as unknown as ToolbarControlAlignment,
);

Viewer-type-specific controls

viewerToolbarControls is called once per viewer type. Use viewerType to conditionally add controls:

viewerToolbarControls: async (_api: IReviewInterfaceApi, viewerType: string, viewerToolbar: IToolbar): Promise<void> => {
  if (viewerType === 'native') {
    await viewerToolbar.createToolbarControl({ /* native-only config */ }, 'right' as unknown as ToolbarControlAlignment);
  }
},