PDF Layers (Optional Content Groups)

← Back to Blog

What Are PDF Layers?

PDF layers — formally known as Optional Content Groups (OCGs) — are a mechanism defined in the PDF specification (ISO 32000) that allows content within a PDF to be selectively shown or hidden. Each layer is a named group; content on the page is associated with one or more groups via Optional Content Membership Dictionaries (OCMDs), and the visibility of that content is determined at render time by the layer's current state.

The optional content feature was introduced in PDF 1.5, and it is one of the most versatile capabilities in the format. Unlike the rendering layers in Photoshop or Illustrator (which are tool-specific internal structures that exist only within those applications), PDF layers are a fully self-contained, interoperable feature defined by an open standard. Any conforming PDF viewer can present layer controls and respond to visibility changes, and layer state can be manipulated programmatically without Acrobat.

The term "layers" is used colloquially because it maps to the familiar concept from authoring tools, but the PDF specification's term "optional content group" is more precise: it describes a named group of content that is optionally included in rendering.

Use Cases for PDF Layers

Optional content groups are used across a wide range of industries and document types:

• Multi-language documents — A single PDF can contain text in multiple languages, each on a separate layer, with only one language visible at a time. This eliminates the need to maintain and distribute separate language editions.
• Print vs screen versions — Rich on-screen annotations, colour backgrounds, and interactive elements can be placed on a screen-only layer, while a separate print layer contains a print-optimised layout. The correct layer set is activated automatically based on whether the viewer is in print or on-screen mode.
• CAD drawings — Engineering drawings exported from AutoCAD, MicroStation, and similar tools map their drawing layers directly to PDF OCGs. Engineers can show or hide annotation layers, dimension layers, title blocks, and discipline-specific overlays without editing the document.
• Cartographic maps — PDF maps from GIS applications (ESRI ArcGIS, QGIS, etc.) use layers for terrain, roads, labels, political boundaries, and thematic data. End users can tailor the map to their needs by toggling layers on and off.
• Variable content documents — Product catalogues or forms can contain optional sections (such as pricing for different regions, or optional product variants) each on a separate layer, with JavaScript or viewer configuration controlling which sections are visible for a given audience.
• Watermarking and confidentiality — A watermark or "CONFIDENTIAL" stamp can be placed on a separate layer, making it easy to produce both a watermarked external version and an unwatermarked internal version from the same source file.

How Layers Are Defined in the PDF Object Model

The optional content infrastructure in a PDF file resides in the document catalog, under the /OCProperties key:

<< /Type /Catalog
   /Pages 2 0 R
   /OCProperties <<
     /OCGs [10 0 R 11 0 R 12 0 R]
     /D << /Name (Default)
            /BaseState /ON
            /ON [10 0 R 11 0 R]
            /OFF [12 0 R]
            /Order [10 0 R 11 0 R 12 0 R]
            /ListMode /AllPages
         >>
   >>
>>

Each OCG is defined by a dictionary object with a /Type /OCG entry and a /Name string that identifies it in the viewer's Layers panel. The /OCProperties dictionary contains:

• /OCGs — an array listing all OCG objects in the document
• /D — the default configuration dictionary, which specifies the initial visibility state of all layers when the document is opened
• /Configs — an optional array of additional configuration dictionaries representing alternative layer presets

Content on a page is associated with a layer by enclosing it within a marked content sequence using the OC tag:

/OC /English BDC
  BT
    /F1 12 Tf
    100 700 Td
    (This is the English text layer.) Tj
  ET
EMC

The property list referenced by /OC is an indirect reference to the OCG dictionary. When the viewer renders the page, it checks each OCG's current visibility state and omits the enclosed content if the group is OFF.

Layer Visibility States and Default Configurations

Each OCG has a current state — ON or OFF — which the viewer maintains as a mutable runtime value. The default configuration dictionary in /OCProperties/D defines the initial state of every layer when the document is first opened or when the user clicks "Reset to default" in the Layers panel.

The /BaseState key in the configuration dictionary sets the starting state for all layers not explicitly listed (/ON or /OFF). Individual overrides are then listed in the /ON and /OFF arrays. The /Order array defines the hierarchical display order of layers in the Layers panel. The /ListMode key (/AllPages, /VisiblePages) controls whether layers are listed even when they do not appear on the current page.

OCGs can also have an /Intent key (/View or /Design) that signals whether the layer is intended for document viewing (should be toggleable by end users) or for document design purposes (intended for authoring tools only, not necessarily shown in the user-facing Layers panel). Most layers in standard documents use the default /View intent.

Optional Content Membership Dictionaries (OCMDs)

An OCMD allows content visibility to be controlled by a combination of OCG states rather than a single group. An OCMD dictionary specifies a set of OCGs and a Boolean expression (/P key) that determines visibility:

• /AllOn — visible when all listed OCGs are ON
• /AnyOn — visible when any listed OCG is ON
• /AllOff — visible when all listed OCGs are OFF
• /AnyOff — visible when any listed OCG is OFF

OCMDs enable sophisticated conditional content arrangements. For example, a "summary section" could be set to appear only when both the "executive audience" layer AND the "English language" layer are ON. Nested layers — where groups are presented in the Layers panel as collapsible parent–child hierarchies — are achieved through the /Order array in the configuration dictionary, not through nesting of OCG objects themselves.

Creating Layers in Authoring Applications

Adobe InDesign

InDesign's layer panel directly maps to PDF OCGs during export. Each InDesign layer becomes a PDF layer with the same name. In the Export Adobe PDF dialog, the General tab includes an Export Layers option; selecting All Layers exports all layers including hidden ones. Selecting Visible & Printable Layers exports only what is currently shown. Selecting Visible Layers exports all visible layers regardless of their print setting.

Adobe Illustrator

Illustrator also maps its layers panel to PDF OCGs. When saving as PDF, the Create Acrobat Layers from Top-Level Layers option in the Save Adobe PDF dialog must be enabled. Sub-layers in Illustrator are flattened into the parent layer in the resulting PDF; only top-level layers become OCGs.

Adobe Acrobat

Acrobat Pro allows creation and management of layers directly via View > Show/Hide > Navigation Panes > Layers. From the Layers panel, new layers can be added by clicking the New Layer icon, and existing page content can be moved to a layer using the Edit Content tools. Acrobat also provides the Flatten Layers option (under the Layers panel menu) which merges all visible layers into the base content stream and removes the OCG infrastructure.

AutoCAD and CAD Applications

When exporting PDFs from AutoCAD, each AutoCAD layer becomes a PDF OCG. The export configuration controls which layers are exported and their initial visibility. The resulting PDF can be viewed in Acrobat with full layer toggling, making PDF a viable distribution format for engineering drawings where different trades need to isolate relevant content.

Scripting Layer Visibility with Acrobat JavaScript

Acrobat JavaScript provides the OCG object and associated methods for reading and setting layer states programmatically:

// Get a reference to the first OCG by name
var ocgs = this.getOCGs();
for (var i = 0; i < ocgs.length; i++) {
  if (ocgs[i].name === "English") {
    ocgs[i].state = true;   // turn layer ON
  }
  if (ocgs[i].name === "French") {
    ocgs[i].state = false;  // turn layer OFF
  }
}

// Toggle a layer from a button action
var layer = this.getOCGs({nPage: 0})[0];
layer.state = !layer.state;

JavaScript-driven layer control is commonly used to implement language selection menus (radio buttons that activate the corresponding language layer and deactivate all others), section toggles in interactive documents, and dynamic data visibility in dashboard-style PDF reports.

Layer scripting can also be triggered from page open/close events, allowing the document to automatically configure layers based on context — for example, switching to a "screen reading" configuration when a mobile viewer is detected, or hiding construction notes layers when a document is opened by an end-user audience.

Printing with Specific Layers

Acrobat's print dialog includes a Print Layers option that determines which layer configuration is used for printing:

• Document and Stamps — prints with the current on-screen layer visibility
• Document — prints the document without annotation layers (stamps, comments)

Individual OCGs can be configured with a /Usage dictionary that specifies per-OCG print behaviour. The /Print sub-dictionary's /PrintState key (/ON or /OFF) sets whether the layer should be printed regardless of its on-screen visibility. This allows, for example, a "screen annotation" layer to be always visible on screen but always suppressed when printing, and a "print-only watermark" layer to be invisible on screen but always printed.

PDF Layers vs Photoshop and Illustrator Layers

It is important to understand the distinction between PDF OCGs and the layers within authoring applications:

• Photoshop layers are a compositing mechanism within PSD files. They carry blend modes, opacity, adjustment effects, and masks that are resolved during flattening. When a Photoshop document is saved as a PDF, the layers are typically flattened into a single merged image unless the file is saved as a Photoshop PDF with layer editing preserved (increasing file size significantly). These preserved editing layers are proprietary extensions, not standard PDF OCGs.
• Illustrator layers are structural containers for artwork objects, with their own visibility and print flags. They can be exported as PDF OCGs (as described above), but only top-level layers are converted; the internal sub-layer hierarchy, blending, and opacity settings are resolved during export.
• PDF OCGs are viewer-controlled visibility toggles on arbitrary page content. They have no concept of compositing order, blend modes, or opacity — they simply include or exclude content from rendering. An OCG cannot make semi-transparent content become opaque; it can only show or hide content that was already rendered at a fixed opacity in the content stream.

This means that round-tripping layer information through PDF — exporting a layered Illustrator file to PDF and reopening it in Illustrator expecting to recover fully editable layers — only works if the PDF was saved with the Illustrator editing capabilities preserved. Standard PDF OCGs do not carry enough information to reconstruct the authoring application's layer model.