Toggle layer (OCG) visibility in a PDF using JavaScript

This guide explains how to programmatically toggle or lock the visibility of optional content group (OCG) layers using several APIs. End users can also adjust layer visibility through the user interface (UI), as the built-in UI guide explains.

Nutrient Web SDK exposes several APIs to manage the OCG layers present in a document:

• instance.getLayers() returns the list of OCG layers present in the document.
• instance.getLayersVisibilityState() returns the IDs of the OCG layers that are currently visible in the document.
• instance.setLayersVisibilityState({ visibleLayerIds: [LayerId] }) makes the listed OCG layers visible and hides the other layers returned by instance.getLayers(). Layers outside that list keep the visibility defined by the PDF. Its promise resolves after the SDK applies the visibility state, and rejects if the operation fails.
• ViewState#sidebarOptions enables you to lock the visibility of OCG layers and set where the sidebar renders visibility and lock icons.

Toggling the OCG layer visibility programmatically

To toggle the visibility of OCG layers programmatically, use the instance.setLayersVisibilityState() method. The example below first gathers the OCG layers present in a document and checks which ones are visible. Finally, it sets a subset of them as visible:

// Get OCG layers in document.
const OCGLayers = await instance.getLayers(); // List of NutrientViewer.OCG.

// Get visible OCG layers.
const visibleLayers = await instance.getLayersVisibilityState();
// visibleLayers = { visibleLayerIds: [86, 72, 121, 118] }

// Set OCG layer IDs `86` and `72` as visible.
await instance.setLayersVisibilityState({ visibleLayerIds: [86, 72] });
// Running this would make these two layers visible while hiding layers `121` and `118`.

Locking the OCG layer visibility programmatically

With Nutrient Web SDK, you can lock the visibility of an OCG layer, which prevents the end user from toggling the layer visibility.

When the sidebar renders a locked OCG layer, the Web SDK shows a lock icon next to it. Locking an item also locks all its children, which show a gray dot instead of the lock icon.

You can control locking layers via the lockedLayers property of the NutrientViewer.ViewState#sidebarOptions for NutrientViewer.SidebarMode.LAYERS.

By default, OCG layers aren’t locked.

The following example locks the visibility of two OCG layers in a document, identified by the ocgId values 86 and 72:

NutrientViewer.load({
  initialViewState: new NutrientViewer.ViewState({
    sidebarOptions: {
      [NutrientViewer.SidebarMode.LAYERS]: {
        lockedLayers: [86, 72] // Array of `ocg.ocgId` present in the document that we want to lock.
        // Other configurations.
      }
    }
  })
});

Document Engine limitations

With Web SDK 1.25 or later and Document Engine 1.20.0 or later, layer visibility changes are local to the viewer. They aren’t saved to or synchronized with the document, and the selection resets when the document reloads or is replaced. This includes replacement after redaction, signing, a content editor save, or applying document operations.

In Document Engine mode, printing, exporting, and downloading use the PDF’s default layer visibility, not the viewer’s current selection, and text in a hidden layer can still be selected. Layers that the layers sidebar doesn’t list keep their PDF-defined visibility. Only standalone mode supports creating layers with instance.createLayer().

With Web SDK 1.25 or later and Document Engine earlier than 1.20.0, instance.getLayersVisibilityState() and instance.setLayersVisibilityState() reject with an error that names the required Document Engine version.