--- title: "PDF page labels guide | What they are and how to set them" canonical_url: "https://www.nutrient.io/guides/pdf-page-labels/" md_url: "https://www.nutrient.io/guides/pdf-page-labels.md" last_updated: "2026-05-25T09:22:39.267Z" description: "PDF page labels explained: How they differ from page indices, the numbering systems the PDF specification supports, and how to read, display, and edit them with Nutrient." --- # PDF page labels A [PDF page label](https://pdfa.org/pdf-ux-page-labels/) is the human-readable name a PDF reader displays for a page — what users see in the toolbar, the table of contents, and the thumbnail strip. It’s separate from the page’s position in the file, which is what code typically operates on. A document with no page label dictionary uses `1`, `2`, `3`, … by default. Once page labels are set, the reader follows them. So a 12-page document might display `i`, `ii`, `iii`, `iv`, `1`, `2`, `3`, `4`, `5`, `6`, `A-1`, `A-2`. ## How page labels are stored Page labels are stored at the document level in the PDF (not on individual pages) and are organized into ranges. Each range has: - A starting page index (where the range begins) - A numbering style (Arabic, Roman, letters, or none) - An optional prefix string - An optional starting value for the numeric portion [Section 12.4.2 of the PDF specification (ISO 32000)](https://www.w3.org/WAI/GL/2014/WD-WCAG20-TECHS-20140107/PDF17) defines five numbering styles plus a “no style” option: | Style key | What it produces | Typical use | | --------- | --------------------------------- | ------------------------------- | | `D` | Decimal Arabic: 1, 2, 3, … | Body content | | `R` | Uppercase Roman: I, II, III | Front matter or formal sections | | `r` | Lowercase Roman: i, ii, iii | Front matter | | `A` | Uppercase letters: A, B, … AA, BB | Appendices | | `a` | Lowercase letters: a, b, … aa, bb | Footnotes or annexes | | (none) | Prefix only, no number | Cover pages, unnumbered inserts | Letter styles wrap by repeating: Page 27 with style `A` becomes `AA`, page 28 becomes `BB`, and so on. The optional prefix is a freeform string prepended to the generated label, producing labels such as `Chapter 1-1`, `A-1`, `Intro`, or `Cover`. A range with a prefix and no style yields the prefix on every page in that range, with no number. ## Page labels vs. page indices vs. printed numbers These three concepts are often conflated: - **Page index** is the position of the page in the file, starting at `0` (or `1`, depending on the API). It’s how every PDF library addresses pages internally. - **Page label** is the metadata string the PDF reader displays for that page. - **Printed page numbers** are part of the page content — drawn as text at render time. A PDF can show `42` on the page without having any page labels set, and vice versa. Most APIs accept page indices, not labels. Resolving a label to an index requires walking the page label ranges or using an SDK helper. ## Page labels in Nutrient Nutrient SDKs help bridge the gap between page indices and the labels users see in the document UI. The exact workflow varies by product, depending on whether you need to display, edit, or process page labels server-side. Use the table below to navigate to the relevant per-product guide. | Task | Product | Guide | | ------------------------------------------------------- | ---------------------- | --------------------------------------------- | | Display page labels in a web viewer | Nutrient Web SDK | [Page label navigation](https://www.nutrient.io/guides/web/features/navigation-page-labels.md) | | Edit page labels client-side in JavaScript | Nutrient Web SDK | [Edit page labels in a PDF](https://www.nutrient.io/guides/web/editor/page-label.md) | | Set page labels server-side as part of a build pipeline | Document Engine | [Change PDF page labels server-side](https://www.nutrient.io/guides/document-engine/editor/page-label.md) | | Display and override labels in iOS apps | Nutrient iOS SDK | [Customizing the page number](https://www.nutrient.io/guides/ios/customizing-pdf-pages/customizing-the-page-number.md) | | Toggle label display in Android apps | Nutrient Android SDK | [Customizing the page number](https://www.nutrient.io/guides/android/customizing-pdf-pages/customizing-the-page-number.md) | | Read, add, modify, or delete page label ranges in.NET | Nutrient.NET SDK | [Page label metadata](https://www.nutrient.io/guides/dotnet/editor/metadata-pdf-page-label.md) | | Display labels in a MAUI viewer | Nutrient.NET MAUI SDK | [Page label navigation](https://www.nutrient.io/guides/maui/user-interface/main-toolbar/page-label-navigation.md) | The sections below summarize how each Nutrient product exposes page label support. ### Nutrient Web SDK Nutrient Web SDK exposes page label edits through its operation API. Calling [`instance.applyOperations`](https://www.nutrient.io/api/web/classes/NutrientViewer.Instance.html#applyoperations) with a [`setPageLabel`](https://www.nutrient.io/api/web/interfaces/DocumentOperations.SetPageLabelOperation.html) operation sets or clears the label for one or more pages. The viewer’s pagination widget displays page labels alongside page numbers, and page label information is available for navigation-related UI. ### Document Engine Document Engine accepts a [`labels`](https://www.nutrient.io/api/reference/document-engine/upstream/#model/Label) array in the [`/build` endpoint instructions](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API). Each entry can target a single page index, a contiguous range, or an explicit list of indices. Use this when page labels are part of a generation, merge, or conversion job — for example, applying Roman numerals to front matter after merging two files. ### Nutrient iOS and Android SDKs Both mobile SDKs read existing page labels and surface them in the table of contents, page position view, and thumbnails. Nutrient Android SDK exposes a [`pageLabelsEnabled`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.configuration.activity/-pdf-activity-configuration/-builder/page-labels-enabled.html) flag in `PdfActivityConfiguration` to suppress them. Nutrient iOS SDK enables you to subclass [`LabelParser`](https://www.nutrient.io/api/ios/documentation/pspdfkit/labelparser) to override what the viewer displays without modifying the underlying PDF. ### Nutrient.NET SDK Nutrient.NET SDK has the most complete API surface for page label ranges. [`GetPageLabel`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14~GdPicture14.GdPicturePDF~GetPageLabel.html) reads an individual label, [`GetPageLabelsRange`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14%20(COM%20-%20ActiveX)~GdPicture14.IGdPicturePDF~GetPageLabelsRange.html) and [`GetPageLabelsRangeCount`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14~GdPicture14.GdPicturePDF~GetPageLabelsRangeCount.html) enumerate the existing ranges, [`AddPageLabelsRange`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14~GdPicture14.GdPicturePDF~AddPageLabelsRange.html) adds a new range with a chosen [`PdfPageLabelStyle`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14%20(COM%20-%20ActiveX)~GdPicture14.PdfPageLabelStyle.html), a family of `SetPageLabelsRange…` methods (`Style`, `Prefix`, `StartPage`, `NumPortion`) modify any field of an existing range, and [`DeletePageLabelsRange`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14~GdPicture14.GdPicturePDF~DeletePageLabelsRange.html) clears one. ### Nutrient.NET MAUI SDK Nutrient.NET MAUI SDK exposes pager-related toolbar integration. Refer to [adding page labels to navigation](https://www.nutrient.io/guides/maui/user-interface/main-toolbar/page-label-navigation.md) for the supported page label navigation behavior and configuration details. ## Next steps For complete Nutrient capabilities, [explore the SDK](https://www.nutrient.io/sdk/web/) or [contact Sales](https://www.nutrient.io/contact-sales/). [Try Nutrient Web SDK](https://www.nutrient.io/sdk/web/) [Explore Document Engine](https://www.nutrient.io/sdk/document-engine/)