Severity: high (for any Bootstrap-styled 3.x app). The advertised 1:1 replacement is missing most of the arg surface that made the legacy helper useful.
Surfaced by: titan Phase 2.4 (Wheels 4.0 upgrade), 2026-05-15.
Description
The upgrade guide and _upgrade-docs/PLAN.md-style migration notes frame paginationNav() as the canonical replacement for paginationLinks(). But paginationNav() is missing arguments that paginationLinks() had and that real-world Bootstrap-styled pagination relies on:
prepend / append — wrap the page-number list with outer markupprependToPage / appendToPage — wrap each page number in <li class=\"page-item\">…</li>anchorDivider — separator between page numbersalwaysShowAnchors — show first/prev/next/last anchors conditionallyaddActiveClassToPrependedParent — push the active class onto the <li> wrapperclass for the page-number anchors (only navClass exists for the outer <nav>)
Result: paginationNav() emits <nav class=\"pagination\">link link link</nav> with no <ul> and bare anchors. Real 3.x apps that styled pagination with the standard Bootstrap idiom (<ul class=\"pagination\"><li class=\"page-item\">…</li></ul>) cannot do a like-for-like swap — their pagination renders unstyled.
Workaround used in titan
Drop down to the underlying primitive pageNumberLinks() (which kept those args), build the <nav><ul> wrapper inline. See the titan worktree at peter/wheels-4-phase-2.4-paginationnav for the working pattern.
Suggested fix
One or both:
- Add
prependToPage / appendToPage / innerWrap args to paginationNav() and pass them through to its internal pageNumberLinks call. This restores like-for-like swap for Bootstrap markup.
- Add an "Migrating Bootstrap-styled pagination" section to the upgrade guide showing the composed-primitive pattern (
firstPageLink / previousPageLink / pageNumberLinks / nextPageLink / lastPageLink) as the documented path for apps that can't use the simplified paginationNav wrapper.
Per-finding from titan's Phase 2.4 work: Bootstrap-styled apps are the dominant 3.x pattern. This is the upgrade path most apps will hit.
cc @bpamiri
Severity: high (for any Bootstrap-styled 3.x app). The advertised 1:1 replacement is missing most of the arg surface that made the legacy helper useful.
Surfaced by: titan Phase 2.4 (Wheels 4.0 upgrade), 2026-05-15.
Description
The upgrade guide and
_upgrade-docs/PLAN.md-style migration notes framepaginationNav()as the canonical replacement forpaginationLinks(). ButpaginationNav()is missing arguments thatpaginationLinks()had and that real-world Bootstrap-styled pagination relies on:prepend/append— wrap the page-number list with outer markupprependToPage/appendToPage— wrap each page number in<li class=\"page-item\">…</li>anchorDivider— separator between page numbersalwaysShowAnchors— show first/prev/next/last anchors conditionallyaddActiveClassToPrependedParent— push the active class onto the<li>wrapperclassfor the page-number anchors (onlynavClassexists for the outer<nav>)Result:
paginationNav()emits<nav class=\"pagination\">link link link</nav>with no<ul>and bare anchors. Real 3.x apps that styled pagination with the standard Bootstrap idiom (<ul class=\"pagination\"><li class=\"page-item\">…</li></ul>) cannot do a like-for-like swap — their pagination renders unstyled.Workaround used in titan
Drop down to the underlying primitive
pageNumberLinks()(which kept those args), build the<nav><ul>wrapper inline. See the titan worktree atpeter/wheels-4-phase-2.4-paginationnavfor the working pattern.Suggested fix
One or both:
prependToPage/appendToPage/innerWrapargs topaginationNav()and pass them through to its internalpageNumberLinkscall. This restores like-for-like swap for Bootstrap markup.firstPageLink/previousPageLink/pageNumberLinks/nextPageLink/lastPageLink) as the documented path for apps that can't use the simplifiedpaginationNavwrapper.Per-finding from titan's Phase 2.4 work: Bootstrap-styled apps are the dominant 3.x pattern. This is the upgrade path most apps will hit.
cc @bpamiri