If you’ve ever opened a PDF and seen page labels like ‘i, ii, iii’ before the first numbered page, or a section using ‘A-1, A-2’ for an appendix, you’ve already seen page labels in action.
A PDF page label is the human-readable identifier a viewer displays in its toolbar, table of contents, and thumbnail strip — independent of the page’s position in the file. Most of us never think twice about them. They’re one of those quiet little features that work so well, you only notice them when something goes wrong: the page number in the toolbar doesn’t match what’s printed on the page, or a “go to page” jump lands somewhere unexpected. But if you’re building anything that reads, displays, or edits PDFs, page labels are something you’ll eventually run into.
This post will walk through what page labels actually are, how the PDF specification models them, the gotchas to watch out for, and which Nutrient product to reach for depending on what you’re trying to do.
Think of a page label as a page’s display name — what shows up in the viewer’s toolbar, table of contents, and thumbnails. It rides alongside the page but isn’t tied to its physical position in the file, which is what your code actually touches.
Internally, the PDF stores labels as a series of ranges. Each range carries its own numbering style (Arabic, Roman, or letters), an optional prefix, and an optional starting number. For a complete breakdown of each component and the five numbering styles the PDF specification supports, see our PDF page labels guide.
If a file ships without any label data, the viewer just counts 1, 2, 3, and so on. As soon as ranges are defined, the viewer follows them. A textbook with four pages of front matter, six pages of body content, and a two-page appendix could end up displaying i, ii, iii, iv, 1, 2, 3, 4, 5, 6, A-1, A-2.
The user sees the labels. Your code, in most cases, still uses page indices. It’s a useful split: page labels are presentation, page indices are addressing.
Page labels are easy to confuse with a few other things, so it’s worth being explicit. They’re not the page index, the page number drawn on the page, or the bookmark hierarchy:
42 on the page without having any page labels set, and vice versa.In real-world PDFs, the page label, the page index, and the printed page number often disagree. A scanned book might have a page label of 1 for what is actually the seventh page in the file, with the printed number 1 baked into the scanned image. All three can drift apart, and accessibility checkers sometimes flag the inconsistency.
Most documents are fine with the default numbering, and you don’t need to think about page labels at all. But there are a handful of cases where they really earn their keep:
A-1, B-1, B-2 for chapters or appendices, so a cross-reference like “see page B-12” stays stable even when other sections grow.Without page labels, none of this is impossible — you can always burn numbers into the page content — but it ties the numbering to the rendered text, makes editing harder, and breaks “go to page” navigation in your viewer.
Page labels look simple until they don’t. Here are the patterns that tend to trip teams up.
There’s nothing in the PDF specification that prevents two pages from having the same label. A document with two ranges, both starting at 1 with style D, will produce two pages labeled 1, two labeled 2, and so on. Viewers handle it, but “go to page” features may jump to the first match, and search results can be ambiguous.
Most APIs accept page indices, not labels. Calling goToPage("iii") on a library that expects an integer is a common mistake. The same applies to structural operations like deleting or duplicating pages — those work on page indices as defined by the API, never on labels. Some libraries provide a separate label-aware lookup, and others don’t. When you do need to resolve a label to an index, walk the label ranges yourself, or use the SDK helper if one exists.
A lot of APIs append a new range rather than replacing the existing ones. If a document already has a range starting at index 0, adding another range at index 0 can leave you with two ranges that disagree about the same pages. Most libraries provide a delete-all or replace operation — make use of it before bulk edits.
Some PDF viewers display page labels but only accept page indices in the “go to page” input. Others accept both. If your application exposes navigation, decide upfront which behavior you want, and make sure the input field’s placeholder reflects it.
A scanned PDF rarely has meaningful page labels — the original print numbering is part of the image, not the structure. If your pipeline runs OCR, page labels won’t be created automatically. They’re a separate metadata edit.
Whether a page label is visible after a PDF is exported, printed, or shared depends entirely on the consuming software. Most desktop viewers respect labels, but some web viewers, mobile apps, and print drivers don’t. If labels are critical to the reader’s experience, it’s worth also showing the number in the page content itself.
Each Nutrient product handles page labels a little differently, depending on whether the focus is viewing, editing, or server-side processing — a viewer reads the label dictionary and renders it, while a server-side API mutates it. For the full reference, including the numbering systems the PDF specification supports and per-product code samples for Web, Document Engine, iOS, Android, .NET, and MAUI, see our PDF page labels guide.
Most viewers display the label alongside the physical page number in the file when a label is set, so users can disambiguate. The format varies by viewer, but the parenthetical is almost always that physical page number — typically one-based and counted from the start of the file — not a second label or an API-level index.
It depends on the API. If a label is part of a range covering several pages, deleting it usually means splitting the range or shrinking it. Nutrient .NET SDK exposes range-level operations directly. Nutrient Web SDK operates per page and lets the underlying engine reconcile ranges for you.
Only barely. Page labels are stored as a small block of metadata inside the PDF. Even a document with hundreds of ranges adds only a few kilobytes.
Page labels are metadata for navigation. They don’t change the page text, the tag tree, or how a screen reader reads content. They do affect what assistive technology announces when a user navigates to a page, so meaningful labels improve the experience for everyone. See accessibility support for the JavaScript PDF viewer for how Nutrient Web SDK handles related accessibility concerns.
Yes, in well-behaved converters. PDF/A and PDF/UA don’t restrict page label dictionaries, and standard conversion tools carry them through. Nutrient preserves the page label dictionary through PDF/A conversion. If you’re seeing labels disappear after conversion, the converter — not the specification — is the culprit.
Page labels are one of those features that sit somewhere between “nice to have” and “absolutely essential,” depending on what you’re building. For a single-section document, the default numbering is plenty. But for anything with front matter, appendices, or merged sections — or any kind of document that needs print and digital numbering to line up — they’re the right tool for the job.
Building a web viewer or generating PDFs on the server? Start with Nutrient Web SDK or Document Engine. Working in a mobile or .NET app? Jump straight to the iOS, Android, .NET, or MAUI guide for your platform. And if you have a more specific question, reach out to our team.
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。