The page labels structure uses a PDF number tree to map physical page indices to labelling schemes. A number tree is an ordered dictionary structure (like a B-tree) that allows efficient lookup of values by integer key. For page labels, each key is a zero-based physical page index, and each value is a page label dictionary:

<strong>Simple example</strong> — A document with 6 pages where pages 0–1 are numbered with lowercase Roman numerals (i, ii) and pages 2–5 with Arabic numerals (1, 2, 3, 4):

<pre><code>/PageLabels &lt;&lt; /Nums [ 0 &lt;&lt; /S /r &gt;&gt; 2 &lt;&lt; /S /D /St 1 &gt;&gt; ] &gt;&gt;</code></pre>

The <code>/Nums</code> array contains pairs of [page_index, label_dict]. Each label dictionary applies from that page index until the next entry. Page 0 uses Roman numerals (/S /r); page 2 starts Arabic numbering (/S /D) at 1 (/St 1).

<strong>/S — Numbering style</strong>: The style determines how page numbers are generated: - <code>/D</code> — Decimal Arabic numerals: 1, 2, 3, 4 ... - <code>/r</code> — Lowercase Roman numerals: i, ii, iii, iv ... - <code>/R</code> — Uppercase Roman numerals: I, II, III, IV ... - <code>/a</code> — Lowercase alphabetic: a, b, c, ... z, aa, ab ... - <code>/A</code> — Uppercase alphabetic: A, B, C, ... Z, AA, AB ... - (absent) — No numeric suffix; the page label is the prefix string alone.

<strong>/St — Starting value</strong>: The integer value at which the sequence begins. Default is 1. Set <code>/St 3</code> to start a section at page 3.

<strong>/P — Prefix string</strong>: A string prepended to the numeric suffix. <code>/P (App-)</code> produces App-1, App-2, App-3. Prefix strings can use any characters, including letters, hyphens, and spaces.

Page labels solve several practical document navigation problems:

<strong>Front matter with Roman numerals</strong> — Academic theses, technical books, and formal reports commonly use lowercase Roman numerals for title pages, table of contents, and prefatory material, switching to Arabic numerals at chapter 1. The page labels structure maps the first N physical pages to /S /r, then sets a new entry with /S /D /St 1 at the first body content page.

<strong>Chapter prefixes</strong> — Technical manuals and multi-part documents sometimes use chapter-prefixed page numbers: 1-1, 1-2, 1-3 ... 2-1, 2-2 ... Each chapter section starts a new /PageLabels entry with the appropriate /P prefix.

<strong>Appendix numbering</strong> — A common pattern is alphabetic appendix prefixes: A-1, A-2 ... B-1, B-2. This uses <code>/P (A-) /S /D /St 1</code> for the first appendix and <code>/P (B-) /S /D /St 1</code> for the second.

<strong>Documents without page numbers</strong> — For pages that should display no number (cover pages, blank dividers), a label entry with no /S and an empty or absent /P produces no displayed label.

<strong>Viewer display</strong> — Adobe Acrobat Reader, Adobe Acrobat Pro, macOS Preview, and Foxit Reader all honour /PageLabels for the page number display in the toolbar and in the Print dialog's page range entry. Chrome's built-in PDF viewer and Firefox's PDF.js viewer also support /PageLabels in current versions.

<strong>Interaction with named destinations</strong> — Internal links and <a href="https://pdftheguide.com/glossary/pdf-destination" target="_blank" rel="noopener">named destinations</a> use physical page object references, not page labels. A link to "page i" targets the physical page object at position 0 — the page label is a display convention, not part of the link target mechanism.

Page labels can be created and modified at multiple stages of document production:

<strong>From authoring tools</strong> — Adobe InDesign has direct support for specifying page numbering sections with start page and style settings; these are exported to /PageLabels in PDF output. Microsoft Word's page numbering sections (Insert > Page Number > Format Page Numbers) are exported to PDF as /PageLabels by Word for Windows when using the Acrobat PDF Maker add-in; the built-in Word Export to PDF does not always preserve page numbering sections correctly.

<strong>In Adobe Acrobat Pro</strong> — The page thumbnail panel allows setting page labels: right-click pages > Page Labels. You can select a range of pages and assign a label scheme (style, start value, prefix). This modifies the /PageLabels number tree in the document catalogue.

<strong>Programmatic creation</strong> — PDF libraries like <a href="https://pdf-lib.js.org/" target="_blank" rel="noopener">pdf-lib</a>, <a href="https://pdfbox.apache.org/" target="_blank" rel="noopener">Apache PDFBox</a>, and <a href="https://pypdf.readthedocs.io/" target="_blank" rel="noopener">pypdf</a> provide APIs for setting page labels. In pdf-lib: <code>pdfDoc.catalog.set(PDFName.of('PageLabels'), ...)</code> (requires constructing the number tree manually). PDFBox has a <code>PDPageLabels</code> class with methods for adding label ranges. pypdf's <code>PdfWriter.set_page_label()</code> method directly sets page label ranges.

<strong>Validation</strong> — <a href="https://verapdf.org/" target="_blank" rel="noopener">veraPDF</a> includes checks for /PageLabels conformance in PDF/A validation. Malformed number trees or invalid /S values are validation errors. Most PDF viewers handle missing /PageLabels gracefully (defaulting to physical page indices) — the entry is optional in the document catalogue.