From 01679fb5e758ac7a053f303f1db7ca1f8560b2f9 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Thu, 16 Jul 2026 21:27:48 -0700
Subject: [PATCH] Add theme variant support to pagination

Colors links, hover, focus, and the active page item via .theme-{color}
classes, matching the pattern already used by alerts and accordions.
Adds a docs example and updates the migration guide.
---
 scss/_pagination.scss                         | 28 ++++++++-----------
 .../content/docs/components/pagination.mdx    | 20 +++++++++++++
 site/src/content/docs/guides/migration.mdx    |  1 +
 3 files changed, 32 insertions(+), 17 deletions(-)

diff --git a/scss/_pagination.scss b/scss/_pagination.scss
index 109a6423f9e3..b2f3a3525f49 100644
--- a/scss/_pagination.scss
+++ b/scss/_pagination.scss
@@ -6,8 +6,6 @@
 @use "mixins/transition" as *;
 @use "mixins/tokens" as *;
 
-// TODO: update pagination to support variant themes (`.theme-*` role tokens)
-
 // stylelint-disable custom-property-no-missing-var-function
 $pagination-tokens: () !default;
 
@@ -27,11 +25,9 @@ $pagination-tokens: defaults(
     --pagination-hover-color: var(--link-hover-color),
     --pagination-hover-bg: var(--bg-1),
     --pagination-hover-border-color: var(--border-color),
-    --pagination-focus-color: var(--link-hover-color),
-    --pagination-focus-bg: var(--bg-2),
-    --pagination-active-color: var(--primary-contrast),
-    --pagination-active-bg: var(--primary-bg),
-    --pagination-active-border-color: var(--primary-bg),
+    --pagination-active-color: var(--theme-contrast, var(--primary-contrast)),
+    --pagination-active-bg: var(--theme-bg, var(--primary-bg)),
+    --pagination-active-border-color: var(--theme-bg, var(--primary-bg)),
     --pagination-disabled-color: var(--fg-3),
     --pagination-disabled-bg: var(--bg-2),
     --pagination-disabled-border-color: var(--border-color),
@@ -66,7 +62,7 @@ $pagination-sizes: defaults(
     min-height: var(--pagination-min-height);
     padding: var(--pagination-padding-y) var(--pagination-padding-x);
     font-size: var(--pagination-font-size);
-    color: var(--pagination-color);
+    color: var(--theme-fg, var(--pagination-color));
     text-decoration: none;
     background-color: var(--pagination-bg);
     border: var(--pagination-border-width) solid var(--pagination-border-color);
@@ -74,24 +70,22 @@ $pagination-sizes: defaults(
 
     &:hover {
       z-index: 2;
-      color: var(--pagination-hover-color);
-      background-color: var(--pagination-hover-bg);
-      border-color: var(--pagination-hover-border-color);
+      color: var(--theme-fg-emphasis, var(--pagination-hover-color));
+      background-color: var(--theme-bg-subtle, var(--pagination-hover-bg));
+      border-color: var(--theme-border, var(--pagination-hover-border-color));
     }
 
     &:focus-visible {
       z-index: 3;
-      color: var(--pagination-focus-color);
-      background-color: var(--pagination-focus-bg);
-      @include focus-ring(true);
+      @include focus-ring(true, var(--theme-focus-ring, var(--focus-ring-color)));
     }
 
     &.active,
     .active > & {
       z-index: 3;
-      color: var(--pagination-active-color);
-      @include gradient-bg(var(--pagination-active-bg));
-      border-color: var(--pagination-active-border-color);
+      color: var(--theme-contrast, var(--pagination-active-color));
+      @include gradient-bg(var(--theme-bg, var(--pagination-active-bg)));
+      border-color: var(--theme-border, var(--pagination-active-border-color));
     }
 
     &.disabled,
diff --git a/site/src/content/docs/components/pagination.mdx b/site/src/content/docs/components/pagination.mdx
index 073a8c7bc597..969d41f10866 100644
--- a/site/src/content/docs/components/pagination.mdx
+++ b/site/src/content/docs/components/pagination.mdx
@@ -5,6 +5,8 @@ toc: true
 css_layer: components
 ---
 
+import { getData } from '@libs/data'
+
 ## Overview
 
 We use a large block of connected links for our pagination, making links hard to miss and easily scalable—all while providing large hit areas. Pagination is built with list HTML elements so screen readers can announce the number of available links. Use a wrapping `<nav>` element to identify it as a navigation section to screen readers and other assistive technologies.
@@ -95,6 +97,24 @@ And just like active page items, you can swap out the disabled `<a>` for a `<spa
 </li>
 ```
 
+## Variants
+
+Add a `.theme-{color}` class to `.pagination` to apply a semantic theme color across the component, including hover, focus, and the active page item.
+
+<Example class="vstack gap-3" code={getData('theme-colors').map((themeColor) => `<nav aria-label="Page navigation example">
+    <ul class="pagination theme-${themeColor.name}">
+      <li class="page-item"><a class="page-link" href="#">Previous</a></li>
+      <li class="page-item"><a class="page-link" href="#">1</a></li>
+      <li class="page-item active">
+        <a class="page-link" href="#" aria-current="page">2</a>
+      </li>
+      <li class="page-item"><a class="page-link" href="#">3</a></li>
+      <li class="page-item"><a class="page-link" href="#">Next</a></li>
+    </ul>
+  </nav>`)} customMarkup={`<ul class="pagination theme-primary"><!--[!code highlight]-->
+    <!-- Page items here -->
+  </ul>`} />
+
 ## Sizing
 
 Fancy larger or smaller pagination? Add `.pagination-lg` or `.pagination-sm` for additional sizes.
diff --git a/site/src/content/docs/guides/migration.mdx b/site/src/content/docs/guides/migration.mdx
index e2fc39f79333..337b3867fe72 100644
--- a/site/src/content/docs/guides/migration.mdx
+++ b/site/src/content/docs/guides/migration.mdx
@@ -226,6 +226,7 @@ Bootstrap 6 is a major release with many breaking changes to modernize our codeb
 - **Card groups now use container queries.** `.card-group` switches to its attached, equal-width row layout with a `@container` query instead of a viewport `@media` query, so it responds to the width of a parent query container rather than the viewport. Wrap the card group in a query container—e.g. add the `.contains-inline` utility to a parent element—or the cards stay stacked.
 - **List group horizontal variants now use container queries.** The `.*:list-group-horizontal` classes switch between vertical and horizontal layouts with `@container` queries instead of viewport `@media` queries, responding to a parent query container rather than the viewport. Wrap the list group in a query container (e.g. `.contains-inline`) for the responsive variants to take effect.
 - **Reworked badge variants.** Badge color variants now use `.badge-subtle` and `.badge-outline` combined with `.theme-*` classes (e.g., `.badge-subtle .theme-primary`), replacing the v5 `.bg-primary` utility pattern on badges.
+- **Added theme variant support to pagination.** Add a `.theme-{color}` class to `.pagination` (e.g., `.pagination.theme-primary`) to color links, hover, focus, and the active page item with a semantic theme color, matching the pattern already used by alerts and accordions.
 - **Updated breadcrumb markup.** Breadcrumbs now use `.breadcrumb-link` as an interactive element with padding, min-height, and hover background, and explicit `.breadcrumb-divider` elements as separators between items. An empty `.breadcrumb-divider` renders a default chevron via a CSS `mask-image` (`--breadcrumb-divider-icon`) tinted with `background-color: currentcolor`; add your own SVG, text, or markup inside it to override. This replaces the v5 `--bs-breadcrumb-divider` content string on the `.breadcrumb-item::before` pseudo-element.
 - **Navbar responsive collapsing now uses the Drawer, not Collapse.** The v5 collapsible navbar—a `.navbar-toggler` toggling a `.collapse.navbar-collapse` region through the Collapse plugin—has been replaced by the [Drawer]([[docsref:/components/drawer]]). On narrow viewports the navigation slides in as a `<dialog class="drawer">`; from your `.{breakpoint}:navbar-expand` breakpoint up it lays out inline as before. Three things change: the toggler targets a drawer (`data-bs-toggle="drawer"`) instead of a collapse; the collapsible region becomes a `<dialog class="drawer">` with `.drawer-header` / `.drawer-body`; and the `.navbar-expand-{bp}` infix becomes the `.{bp}:navbar-expand` prefix. The v5 `.navbar-light` / `.navbar-dark` color-scheme classes have also been removed—set the surface with a background utility such as `.bg-1` and let [color modes]([[docsref:/customize/color-modes]]) handle light and dark.