modern-pdf-lib

---

modern-pdf-lib / PdfStructureTree

Class: PdfStructureTree

Defined in: src/accessibility/structureTree.ts:378

The structure tree for a tagged PDF document.

Manages the root Document element, assigns marked-content IDs (MCIDs), and provides serialization to/from PDF dictionaries.

Usage:

const tree = doc.createStructureTree();
const heading = tree.addElement(null, 'H1', { altText: 'Main heading' });
tree.assignMcid(heading, 0);

const para = tree.addElement(null, 'P');
tree.assignMcid(para, 0);

Constructors

Constructor

new PdfStructureTree(): PdfStructureTree

Defined in: src/accessibility/structureTree.ts:385

Returns

PdfStructureTree

Properties

root

readonly root: PdfStructureElement

Defined in: src/accessibility/structureTree.ts:380

The root Document structure element.

Methods

addElement()

addElement(parent, type, options?): PdfStructureElement

Defined in: src/accessibility/structureTree.ts:398

Add an element to the structure tree.

Parameters

parent

The parent element, or null to add directly under the root Document element.

PdfStructureElement | null

type

StructureType

The structure type of the new element.

options?

StructureElementOptions

Optional attributes for the element.

Returns

PdfStructureElement

The newly created element.

---

assignMcid()

assignMcid(element, pageIndex): number

Defined in: src/accessibility/structureTree.ts:432

Assign a marked-content ID to an element and associate it with a page. The MCID links the structure element to the actual content on the page (via BMC/BDC operators in the content stream).

Parameters

element

PdfStructureElement

The element to assign an MCID to.

pageIndex

number

The zero-based page index the content appears on.

Returns

number

The assigned MCID.

---

getAllElements()

getAllElements(): PdfStructureElement[]

Defined in: src/accessibility/structureTree.ts:442

Return all elements in the tree (depth-first traversal from root).

Returns

PdfStructureElement[]

---

getNextMcid()

getNextMcid(): number

Defined in: src/accessibility/structureTree.ts:449

Return the current MCID counter value (useful for testing).

Returns

number

---

removeElement()

removeElement(element): void

Defined in: src/accessibility/structureTree.ts:413

Remove an element from the tree.

Parameters

element

PdfStructureElement

The element to remove (must not be the root).

Returns

void

Throws

If the element is the root or has no parent.

---

toDict()

toDict(registry, pageRefs): object

Defined in: src/accessibility/structureTree.ts:463

Serialize the structure tree to a /StructTreeRoot dictionary.

The resulting dict is suitable for embedding in the PDF catalog as /StructTreeRoot.

Parameters

registry

PdfObjectRegistry

Object registry for allocating indirect references.

pageRefs

readonly PdfRef[]

Array of page references indexed by page number.

Returns

object

An object containing the StructTreeRoot ref and dict.

dict

dict: PdfDict

ref

ref: PdfRef

---

validate()

validate(): AccessibilityIssue[]

Defined in: src/accessibility/structureTree.ts:736

Validate the structure tree for common accessibility issues.

Checks:

• Heading hierarchy (no skipped levels)
• Table structure completeness
• Illustration elements have alt text
• List structure completeness

Returns

AccessibilityIssue[]

An array of AccessibilityIssue objects.

---

fromDict()

static fromDict(dict, resolver): PdfStructureTree

Defined in: src/accessibility/structureTree.ts:607

Reconstruct a structure tree from a /StructTreeRoot dictionary.

Parameters

dict

PdfDict

The /StructTreeRoot dictionary.

resolver

(ref) => PdfObject | undefined

A function that resolves indirect references to their underlying PDF objects.

Returns

PdfStructureTree

A new PdfStructureTree.