Page number

The page's own number, filled in for you.

{
  "Type": "PageNumber",
  "Alignment": "Center"
}

Stacked in Elements it sits wherever the content above it ends, which is rarely what you want for a folio. For a number pinned to the same spot on every page, put it in the page's Foreground with a Position, remembering that placed elements ignore Alignment:

{
  "Type": "PageNumber",
  "Position": { "X": 96, "Y": 296 }
}

The number counts from 1, so the first page of the book shows 1. By default it's the page's position in the book as a whole, matching how JumpToPage counts (only that action is 0-based).

Unlike every other text element, PageNumber takes no Text. Giving it one is ignored rather than treated as an error.

Page number fields

Property	Type	Default	Description
Scope optional	Book | Chapter	Book	What the number counts from. Chapter starts again at 1 on each chapter's first page, rather than running through the book. No effect in a book without chapters, where the whole book counts as one.
Format optional	string	—	A wrapper around the number, where {0} is the number. "Page {0}" gives Page 4, "- {0} -" gives - 4 -. When omitted the number is drawn on its own.

{
  "Type": "PageNumber",
  "Format": "- {0} -",
  "Scope": "Chapter",
  "Alignment": "Center"
}

Text fields

FontType defaults to Small, the game's small font.

Property	Type	Default	Description
FontType optional	font type	Small	Which font to draw the number with.
TextColor optional	color	the book's default	The number's colour.

Common fields

Scale on a PageNumber is the font scale, since it has no sprite.

Property	Type	Default	Description
Type required	element type	—	Which kind of element this is. Determines every other field below.
Id optional	string	—	An optional identifier for this element. Not used for navigation, purely for your own reference.
Alignment optional	Left | Center | Right	Left	Where the element sits within its container's width. Only has an effect when the element is narrower than the space available (see Layout).
Scale optional	number	1	The element's scale. Its meaning depends on the element type: sprite scale for Image, Panel, Banner, Button and Divider. Font scale for Title, Heading and Paragraph. See Units and scale.
SpacingAfter optional	int	8	The gap between this element and the next one, in unscaled sprite pixels × Scale. Not applied after the last visible element, so a trailing gap can't appear at the bottom of a page or panel.
MarginLeft optional	int	0	Space reserved to the element's left, in unscaled sprite pixels × Scale. This narrows the width the element measures against, so text wraps at the indented width rather than overflowing.
MarginRight optional	int	0	Space reserved to the element's right, in unscaled sprite pixels × Scale.
Position optional	Point	{ X: 0, Y: 0 }	The element's position, in screen pixels. Only used in Background, Foreground, Underlay and Overlay, where elements are placed rather than stacked. Unlike every other spacing field this is not multiplied by Scale. Changing an element's scale resizes it in place rather than moving it.
Condition optional	string	—	A game state query. When it evaluates false the element is hidden, and elements below it close the gap. Re-checked several times a second while the book is open.
Action optional	string	—	A trigger action run when the element is clicked. When set, the element becomes interactive: any element type can have one, not just Button.
Actions optional	list of string	—	Trigger actions run in order when the element is clicked. Combined with Action rather than replacing it, so an element with both runs Action first.
Sound optional	string	bigSelect	The cue played when the element is clicked. Only used when Action or Actions is set, and played once however many actions run. Set to null for a silent click.
HoverAction optional	string	—	A trigger action run when the cursor moves onto the element. Runs on entry, not while the cursor rests there. Sound doesn't apply.
HoverActions optional	list of string	—	Trigger actions run in order when the cursor moves onto the element. Combined with HoverAction rather than replacing it, so an element with both runs HoverAction first.
DisplayName optional	string	—	The bold title of the element's hover tooltip. Works in every list, including a page's Background and Foreground.
Description optional	string	—	The body of the element's hover tooltip. Works in every list, including a page's Background and Foreground, where setting it is also what makes an otherwise decorative element reachable by the cursor.

Gotchas

It needs a page. A PageNumber in a book's Underlay or Overlay has no single page to name, since those span the whole book, so it draws nothing and logs a warning once. Put it in the page's Elements, Background or Foreground instead.

Numbering follows the book, not the reader. A page shows the same number however the reader arrived at it. Which page is number 1 depends on Scope, not on where they started reading.

A repeated chapter ID restarts the count. Chapters are contiguous runs of pages, so pages sharing a ChapterId in two separate runs are two chapters (Parchment already warns about this at load). With Scope set to Chapter, the second run counts from 1 again.

A bad Format drops the element. It's checked at load, so "Page {1}" (there's only ever a {0}) fails validation with the reason in the SMAPI log. For a literal brace, double it: "{{0}}" draws {0}. Content Patcher reads {{ as the start of a token, so put a literal brace in a Format only via a CP token holding it.

A skipped page still shifts the numbers. A page dropped at load for failing validation isn't in the book, so every page after it shifts up by one. Check the SMAPI log if the numbers look off by one.