From 7017b0badf7ebccd775fc4e1f3c0d0f6b981bad9 Mon Sep 17 00:00:00 2001
From: seojcarlos <jcarlos@convertiam.com>
Date: Sun, 5 Apr 2026 02:14:47 +0200
Subject: [PATCH 1/5] feat(pagination): add getPageUrl prop for SEO-friendly
 anchor links

When getPageUrl is provided, pagination buttons render as <a> elements
instead of <button> elements, making pagination links crawlable by
search engines.

Fixes #791
---
 .../components/Pagination/Pagination.test.tsx | 90 +++++++++++++++++++
 .../src/components/Pagination/Pagination.tsx  | 17 +++-
 .../Pagination/PaginationButton.tsx           | 47 ++++++++--
 3 files changed, 146 insertions(+), 8 deletions(-)

diff --git a/packages/ui/src/components/Pagination/Pagination.test.tsx b/packages/ui/src/components/Pagination/Pagination.test.tsx
index 8367cd51c3..0e86694d66 100644
--- a/packages/ui/src/components/Pagination/Pagination.test.tsx
+++ b/packages/ui/src/components/Pagination/Pagination.test.tsx
@@ -205,6 +205,96 @@ describe("Pagination", () => {
       );
     });
 
+    describe("getPageUrl", () => {
+      it("should render anchor elements when getPageUrl is provided", () => {
+        render(
+          <Pagination
+            currentPage={2}
+            onPageChange={() => undefined}
+            totalPages={5}
+            getPageUrl={(page) => `/blog?page=${page}`}
+          />,
+        );
+
+        const links = screen.getAllByRole("link");
+        expect(links.length).toBeGreaterThan(0);
+      });
+
+      it("should set correct href on page links", () => {
+        render(
+          <Pagination
+            currentPage={2}
+            onPageChange={() => undefined}
+            totalPages={5}
+            getPageUrl={(page) => `/blog?page=${page}`}
+          />,
+        );
+
+        const links = screen.getAllByRole("link");
+        const hrefs = links.map((link) => link.getAttribute("href"));
+
+        expect(hrefs).toContain("/blog?page=1");
+        expect(hrefs).toContain("/blog?page=3");
+      });
+
+      it("should not render previous as link on first page", () => {
+        render(
+          <Pagination
+            currentPage={1}
+            onPageChange={() => undefined}
+            totalPages={5}
+            getPageUrl={(page) => `/blog?page=${page}`}
+          />,
+        );
+
+        const prevButton = previousButton();
+        expect(prevButton.tagName).toBe("BUTTON");
+        expect(prevButton).toBeDisabled();
+      });
+
+      it("should not render next as link on last page", () => {
+        render(
+          <Pagination
+            currentPage={5}
+            onPageChange={() => undefined}
+            totalPages={5}
+            getPageUrl={(page) => `/blog?page=${page}`}
+          />,
+        );
+
+        const nextBtn = nextButton();
+        expect(nextBtn.tagName).toBe("BUTTON");
+        expect(nextBtn).toBeDisabled();
+      });
+
+      it("should render previous and next as links on middle pages", () => {
+        render(
+          <Pagination
+            currentPage={3}
+            onPageChange={() => undefined}
+            totalPages={5}
+            getPageUrl={(page) => `/blog?page=${page}`}
+          />,
+        );
+
+        const links = screen.getAllByRole("link");
+        const hrefs = links.map((link) => link.getAttribute("href"));
+
+        expect(hrefs).toContain("/blog?page=2");
+        expect(hrefs).toContain("/blog?page=4");
+      });
+
+      it("should render buttons when getPageUrl is not provided", () => {
+        render(<Pagination currentPage={2} onPageChange={() => undefined} totalPages={5} />);
+
+        const links = screen.queryAllByRole("link");
+        expect(links).toHaveLength(0);
+
+        const btns = screen.getAllByRole("button");
+        expect(btns.length).toBeGreaterThan(0);
+      });
+    });
+
     it("should throw an error if totalPages is not a positive integer", () => {
       expect(() => render(<Pagination currentPage={1} onPageChange={() => undefined} totalPages={-1} />)).toThrow(
         "Invalid props: totalPages must be a positive integer",
diff --git a/packages/ui/src/components/Pagination/Pagination.tsx b/packages/ui/src/components/Pagination/Pagination.tsx
index a4fd4c9ee2..192a994917 100644
--- a/packages/ui/src/components/Pagination/Pagination.tsx
+++ b/packages/ui/src/components/Pagination/Pagination.tsx
@@ -55,6 +55,12 @@ export interface BasePaginationProps extends ComponentProps<"nav">, ThemingProps
 
 export interface DefaultPaginationProps extends BasePaginationProps {
   layout?: "navigation" | "pagination";
+  /**
+   * A function that returns a URL for a given page number. When provided, pagination buttons
+   * render as `<a>` elements instead of `<button>` elements, improving SEO by making
+   * pagination links crawlable by search engines.
+   */
+  getPageUrl?: (page: number) => string;
   renderPaginationButton?: (props: PaginationButtonProps) => ReactNode;
   totalPages: number;
 }
@@ -82,6 +88,7 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
   const {
     className,
     currentPage,
+    getPageUrl,
     layout = "pagination",
     nextLabel = "Next",
     onPageChange,
@@ -103,12 +110,15 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
   const lastPage = Math.min(Math.max(layout === "pagination" ? currentPage + 2 : currentPage + 4, 5), totalPages);
   const firstPage = Math.max(1, lastPage - 4);
 
+  const previousPage = Math.max(currentPage - 1, 1);
+  const nextPage = Math.min(currentPage + 1, totalPages);
+
   function goToNextPage() {
-    onPageChange(Math.min(currentPage + 1, totalPages));
+    onPageChange(nextPage);
   }
 
   function goToPreviousPage() {
-    onPageChange(Math.max(currentPage - 1, 1));
+    onPageChange(previousPage);
   }
 
   return (
@@ -119,6 +129,7 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
             className={twMerge(theme.pages.previous.base, showIcon && theme.pages.showIcon)}
             onClick={goToPreviousPage}
             disabled={currentPage === 1}
+            href={getPageUrl && currentPage > 1 ? getPageUrl(previousPage) : undefined}
           >
             {showIcon && <ChevronLeftIcon aria-hidden className={theme.pages.previous.icon} />}
             {previousLabel}
@@ -131,6 +142,7 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
                 className: twMerge(theme.pages.selector.base, currentPage === page && theme.pages.selector.active),
                 active: page === currentPage,
                 onClick: () => onPageChange(page),
+                href: getPageUrl ? getPageUrl(page) : undefined,
                 children: page,
               })}
             </li>
@@ -140,6 +152,7 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
             className={twMerge(theme.pages.next.base, showIcon && theme.pages.showIcon)}
             onClick={goToNextPage}
             disabled={currentPage === totalPages}
+            href={getPageUrl && currentPage < totalPages ? getPageUrl(nextPage) : undefined}
           >
             {nextLabel}
             {showIcon && <ChevronRightIcon aria-hidden className={theme.pages.next.icon} />}
diff --git a/packages/ui/src/components/Pagination/PaginationButton.tsx b/packages/ui/src/components/Pagination/PaginationButton.tsx
index eff09c875e..c20958b4bc 100644
--- a/packages/ui/src/components/Pagination/PaginationButton.tsx
+++ b/packages/ui/src/components/Pagination/PaginationButton.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { forwardRef, type ComponentProps, type ReactEventHandler, type ReactNode } from "react";
+import { forwardRef, type ComponentProps, type ReactEventHandler, type ReactNode, type Ref } from "react";
 import { get } from "../../helpers/get";
 import { useResolveTheme } from "../../helpers/resolve-theme";
 import { twMerge } from "../../helpers/tailwind-merge";
@@ -18,15 +18,17 @@ export interface PaginationButtonProps extends ComponentProps<"button">, Theming
   active?: boolean;
   children?: ReactNode;
   className?: string;
+  href?: string;
   onClick?: ReactEventHandler<HTMLButtonElement>;
 }
 
 export interface PaginationPrevButtonProps extends Omit<PaginationButtonProps, "active"> {
   disabled?: boolean;
+  href?: string;
 }
 
-export const PaginationButton = forwardRef<HTMLButtonElement, PaginationButtonProps>(
-  ({ active, children, className, onClick, theme: customTheme, clearTheme, applyTheme, ...props }, ref) => {
+export const PaginationButton = forwardRef<HTMLButtonElement | HTMLAnchorElement, PaginationButtonProps>(
+  ({ active, children, className, href, onClick, theme: customTheme, clearTheme, applyTheme, ...props }, ref) => {
     const provider = useThemeProvider();
     const theme = useResolveTheme(
       [paginationTheme, provider.theme?.pagination, customTheme],
@@ -34,11 +36,27 @@ export const PaginationButton = forwardRef<HTMLButtonElement, PaginationButtonPr
       [get(provider.applyTheme, "pagination"), applyTheme],
     );
 
+    const mergedClassName = twMerge(active && theme.pages.selector.active, className);
+
+    if (href) {
+      return (
+        <a
+          ref={ref as Ref<HTMLAnchorElement>}
+          href={href}
+          className={mergedClassName}
+          onClick={onClick as unknown as ReactEventHandler<HTMLAnchorElement>}
+          {...(props as ComponentProps<"a">)}
+        >
+          {children}
+        </a>
+      );
+    }
+
     return (
       <button
-        ref={ref}
+        ref={ref as Ref<HTMLButtonElement>}
         type="button"
-        className={twMerge(active && theme.pages.selector.active, className)}
+        className={mergedClassName}
         onClick={onClick}
         {...props}
       >
@@ -53,6 +71,7 @@ PaginationButton.displayName = "PaginationButton";
 export function PaginationNavigation({
   children,
   className,
+  href,
   onClick,
   disabled = false,
   theme: customTheme,
@@ -67,10 +86,26 @@ export function PaginationNavigation({
     [get(provider.applyTheme, "pagination"), applyTheme],
   );
 
+  const mergedClassName = twMerge(disabled && theme.pages.selector.disabled, className);
+
+  if (href && !disabled) {
+    return (
+      <a
+        href={href}
+        className={mergedClassName}
+        onClick={onClick as unknown as ReactEventHandler<HTMLAnchorElement>}
+        aria-disabled={disabled}
+        {...(props as ComponentProps<"a">)}
+      >
+        {children}
+      </a>
+    );
+  }
+
   return (
     <button
       type="button"
-      className={twMerge(disabled && theme.pages.selector.disabled, className)}
+      className={mergedClassName}
       disabled={disabled}
       onClick={onClick}
       {...props}

From 5e2211988985953baf64e4d32983bedff5ee7847 Mon Sep 17 00:00:00 2001
From: seojcarlos <jcarlos@convertiam.com>
Date: Sun, 5 Apr 2026 02:19:17 +0200
Subject: [PATCH 2/5] style: fix prettier formatting

---
 .../ui/src/components/Pagination/PaginationButton.tsx     | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/packages/ui/src/components/Pagination/PaginationButton.tsx b/packages/ui/src/components/Pagination/PaginationButton.tsx
index c20958b4bc..05ba038414 100644
--- a/packages/ui/src/components/Pagination/PaginationButton.tsx
+++ b/packages/ui/src/components/Pagination/PaginationButton.tsx
@@ -103,13 +103,7 @@ export function PaginationNavigation({
   }
 
   return (
-    <button
-      type="button"
-      className={mergedClassName}
-      disabled={disabled}
-      onClick={onClick}
-      {...props}
-    >
+    <button type="button" className={mergedClassName} disabled={disabled} onClick={onClick} {...props}>
       {children}
     </button>
   );

From 09f4ae4598c71a34a5af59fd565e4ca9d61ab16b Mon Sep 17 00:00:00 2001
From: seojcarlos <jcarlos@convertiam.com>
Date: Sun, 5 Apr 2026 02:26:55 +0200
Subject: [PATCH 3/5] refactor(pagination): use discriminated union types for
 button/anchor variants

Replace unsafe type casts with a proper discriminated union pattern.
PaginationButtonProps and PaginationPrevButtonProps now use href as the
discriminator: when href is provided, anchor-specific props apply;
otherwise, button-specific props apply. This removes all 'as unknown as'
casts and ensures type safety at compile time.

Also removes redundant aria-disabled on enabled anchor elements.
---
 .../src/components/Pagination/Pagination.tsx  | 32 ++++----
 .../Pagination/PaginationButton.tsx           | 73 ++++++++++---------
 2 files changed, 59 insertions(+), 46 deletions(-)

diff --git a/packages/ui/src/components/Pagination/Pagination.tsx b/packages/ui/src/components/Pagination/Pagination.tsx
index 192a994917..4caf0aa001 100644
--- a/packages/ui/src/components/Pagination/Pagination.tsx
+++ b/packages/ui/src/components/Pagination/Pagination.tsx
@@ -121,6 +121,9 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
     onPageChange(previousPage);
   }
 
+  const previousHref = getPageUrl && currentPage > 1 ? getPageUrl(previousPage) : undefined;
+  const nextHref = getPageUrl && currentPage < totalPages ? getPageUrl(nextPage) : undefined;
+
   return (
     <nav ref={ref} className={twMerge(theme.base, className)} {...restProps}>
       <ul className={theme.pages.base}>
@@ -129,30 +132,33 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
             className={twMerge(theme.pages.previous.base, showIcon && theme.pages.showIcon)}
             onClick={goToPreviousPage}
             disabled={currentPage === 1}
-            href={getPageUrl && currentPage > 1 ? getPageUrl(previousPage) : undefined}
+            {...(previousHref ? { href: previousHref } : {})}
           >
             {showIcon && <ChevronLeftIcon aria-hidden className={theme.pages.previous.icon} />}
             {previousLabel}
           </PaginationNavigation>
         </li>
         {layout === "pagination" &&
-          range(firstPage, lastPage).map((page: number) => (
-            <li aria-current={page === currentPage ? "page" : undefined} key={page}>
-              {renderPaginationButton({
-                className: twMerge(theme.pages.selector.base, currentPage === page && theme.pages.selector.active),
-                active: page === currentPage,
-                onClick: () => onPageChange(page),
-                href: getPageUrl ? getPageUrl(page) : undefined,
-                children: page,
-              })}
-            </li>
-          ))}
+          range(firstPage, lastPage).map((page: number) => {
+            const pageHref = getPageUrl ? getPageUrl(page) : undefined;
+            return (
+              <li aria-current={page === currentPage ? "page" : undefined} key={page}>
+                {renderPaginationButton({
+                  className: twMerge(theme.pages.selector.base, currentPage === page && theme.pages.selector.active),
+                  active: page === currentPage,
+                  onClick: () => onPageChange(page),
+                  ...(pageHref ? { href: pageHref } : {}),
+                  children: page,
+                })}
+              </li>
+            );
+          })}
         <li>
           <PaginationNavigation
             className={twMerge(theme.pages.next.base, showIcon && theme.pages.showIcon)}
             onClick={goToNextPage}
             disabled={currentPage === totalPages}
-            href={getPageUrl && currentPage < totalPages ? getPageUrl(nextPage) : undefined}
+            {...(nextHref ? { href: nextHref } : {})}
           >
             {nextLabel}
             {showIcon && <ChevronRightIcon aria-hidden className={theme.pages.next.icon} />}
diff --git a/packages/ui/src/components/Pagination/PaginationButton.tsx b/packages/ui/src/components/Pagination/PaginationButton.tsx
index 05ba038414..6a3a801593 100644
--- a/packages/ui/src/components/Pagination/PaginationButton.tsx
+++ b/packages/ui/src/components/Pagination/PaginationButton.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { forwardRef, type ComponentProps, type ReactEventHandler, type ReactNode, type Ref } from "react";
+import { forwardRef, type ComponentProps, type ReactNode, type Ref } from "react";
 import { get } from "../../helpers/get";
 import { useResolveTheme } from "../../helpers/resolve-theme";
 import { twMerge } from "../../helpers/tailwind-merge";
@@ -14,21 +14,44 @@ export interface PaginationButtonTheme {
   disabled: string;
 }
 
-export interface PaginationButtonProps extends ComponentProps<"button">, ThemingProps<PaginationButtonTheme> {
+interface PaginationButtonBaseProps extends ThemingProps<PaginationButtonTheme> {
   active?: boolean;
   children?: ReactNode;
   className?: string;
-  href?: string;
-  onClick?: ReactEventHandler<HTMLButtonElement>;
 }
 
-export interface PaginationPrevButtonProps extends Omit<PaginationButtonProps, "active"> {
+type PaginationButtonAsButton = PaginationButtonBaseProps &
+  Omit<ComponentProps<"button">, keyof PaginationButtonBaseProps> & {
+    href?: never;
+  };
+
+type PaginationButtonAsAnchor = PaginationButtonBaseProps &
+  Omit<ComponentProps<"a">, keyof PaginationButtonBaseProps> & {
+    href: string;
+  };
+
+export type PaginationButtonProps = PaginationButtonAsButton | PaginationButtonAsAnchor;
+
+interface PaginationNavigationBaseProps extends ThemingProps<PaginationButtonTheme> {
+  children?: ReactNode;
+  className?: string;
   disabled?: boolean;
-  href?: string;
 }
 
+type PaginationNavigationAsButton = PaginationNavigationBaseProps &
+  Omit<ComponentProps<"button">, keyof PaginationNavigationBaseProps> & {
+    href?: never;
+  };
+
+type PaginationNavigationAsAnchor = PaginationNavigationBaseProps &
+  Omit<ComponentProps<"a">, keyof PaginationNavigationBaseProps> & {
+    href: string;
+  };
+
+export type PaginationPrevButtonProps = PaginationNavigationAsButton | PaginationNavigationAsAnchor;
+
 export const PaginationButton = forwardRef<HTMLButtonElement | HTMLAnchorElement, PaginationButtonProps>(
-  ({ active, children, className, href, onClick, theme: customTheme, clearTheme, applyTheme, ...props }, ref) => {
+  ({ active, children, className, theme: customTheme, clearTheme, applyTheme, ...props }, ref) => {
     const provider = useThemeProvider();
     const theme = useResolveTheme(
       [paginationTheme, provider.theme?.pagination, customTheme],
@@ -38,28 +61,18 @@ export const PaginationButton = forwardRef<HTMLButtonElement | HTMLAnchorElement
 
     const mergedClassName = twMerge(active && theme.pages.selector.active, className);
 
-    if (href) {
+    if ("href" in props && props.href) {
+      const { href, ...anchorProps } = props;
       return (
-        <a
-          ref={ref as Ref<HTMLAnchorElement>}
-          href={href}
-          className={mergedClassName}
-          onClick={onClick as unknown as ReactEventHandler<HTMLAnchorElement>}
-          {...(props as ComponentProps<"a">)}
-        >
+        <a ref={ref as Ref<HTMLAnchorElement>} href={href} className={mergedClassName} {...anchorProps}>
           {children}
         </a>
       );
     }
 
+    const { href: _, ...buttonProps } = props as PaginationButtonAsButton;
     return (
-      <button
-        ref={ref as Ref<HTMLButtonElement>}
-        type="button"
-        className={mergedClassName}
-        onClick={onClick}
-        {...props}
-      >
+      <button ref={ref as Ref<HTMLButtonElement>} type="button" className={mergedClassName} {...buttonProps}>
         {children}
       </button>
     );
@@ -71,8 +84,6 @@ PaginationButton.displayName = "PaginationButton";
 export function PaginationNavigation({
   children,
   className,
-  href,
-  onClick,
   disabled = false,
   theme: customTheme,
   clearTheme,
@@ -88,22 +99,18 @@ export function PaginationNavigation({
 
   const mergedClassName = twMerge(disabled && theme.pages.selector.disabled, className);
 
-  if (href && !disabled) {
+  if ("href" in props && props.href && !disabled) {
+    const { href, ...anchorProps } = props;
     return (
-      <a
-        href={href}
-        className={mergedClassName}
-        onClick={onClick as unknown as ReactEventHandler<HTMLAnchorElement>}
-        aria-disabled={disabled}
-        {...(props as ComponentProps<"a">)}
-      >
+      <a href={href} className={mergedClassName} {...anchorProps}>
         {children}
       </a>
     );
   }
 
+  const { href: _, ...buttonProps } = props as PaginationNavigationAsButton;
   return (
-    <button type="button" className={mergedClassName} disabled={disabled} onClick={onClick} {...props}>
+    <button type="button" className={mergedClassName} disabled={disabled} {...buttonProps}>
       {children}
     </button>
   );

From 59b749f32c3e1ce52492ddf1ae54ea57a369b301 Mon Sep 17 00:00:00 2001
From: seojcarlos <jcarlos@convertiam.com>
Date: Sun, 5 Apr 2026 12:36:17 +0200
Subject: [PATCH 4/5] refactor(pagination): address code review feedback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Make onPageChange optional when getPageUrl is provided, enabling
  pure SEO anchor navigation without requiring a no-op callback
- Add forwardRef to PaginationNavigation for consistency with
  PaginationButton and to support ref-based focus management
- Remove redundant active class from parent className — let the
  PaginationButton component handle active styling via the active prop
---
 .../src/components/Pagination/Pagination.tsx  | 16 +++--
 .../Pagination/PaginationButton.tsx           | 62 +++++++++----------
 2 files changed, 42 insertions(+), 36 deletions(-)

diff --git a/packages/ui/src/components/Pagination/Pagination.tsx b/packages/ui/src/components/Pagination/Pagination.tsx
index 4caf0aa001..954ae6fac4 100644
--- a/packages/ui/src/components/Pagination/Pagination.tsx
+++ b/packages/ui/src/components/Pagination/Pagination.tsx
@@ -48,7 +48,12 @@ export interface BasePaginationProps extends ComponentProps<"nav">, ThemingProps
   layout?: "navigation" | "pagination" | "table";
   currentPage: number;
   nextLabel?: string;
-  onPageChange: (page: number) => void;
+  /**
+   * Callback fired when a page is selected. Required when `getPageUrl` is not provided.
+   * When `getPageUrl` is provided, this is optional — if omitted, the anchor links handle
+   * navigation natively without client-side routing.
+   */
+  onPageChange?: (page: number) => void;
   previousLabel?: string;
   showIcons?: boolean;
 }
@@ -66,6 +71,7 @@ export interface DefaultPaginationProps extends BasePaginationProps {
 }
 export interface TablePaginationProps extends BasePaginationProps {
   layout: "table";
+  onPageChange: (page: number) => void;
   itemsPerPage: number;
   totalItems: number;
 }
@@ -114,11 +120,11 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
   const nextPage = Math.min(currentPage + 1, totalPages);
 
   function goToNextPage() {
-    onPageChange(nextPage);
+    onPageChange?.(nextPage);
   }
 
   function goToPreviousPage() {
-    onPageChange(previousPage);
+    onPageChange?.(previousPage);
   }
 
   const previousHref = getPageUrl && currentPage > 1 ? getPageUrl(previousPage) : undefined;
@@ -144,9 +150,9 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
             return (
               <li aria-current={page === currentPage ? "page" : undefined} key={page}>
                 {renderPaginationButton({
-                  className: twMerge(theme.pages.selector.base, currentPage === page && theme.pages.selector.active),
+                  className: theme.pages.selector.base,
                   active: page === currentPage,
-                  onClick: () => onPageChange(page),
+                  onClick: () => onPageChange?.(page),
                   ...(pageHref ? { href: pageHref } : {}),
                   children: page,
                 })}
diff --git a/packages/ui/src/components/Pagination/PaginationButton.tsx b/packages/ui/src/components/Pagination/PaginationButton.tsx
index 6a3a801593..7a5a0ac48e 100644
--- a/packages/ui/src/components/Pagination/PaginationButton.tsx
+++ b/packages/ui/src/components/Pagination/PaginationButton.tsx
@@ -81,39 +81,39 @@ export const PaginationButton = forwardRef<HTMLButtonElement | HTMLAnchorElement
 
 PaginationButton.displayName = "PaginationButton";
 
-export function PaginationNavigation({
-  children,
-  className,
-  disabled = false,
-  theme: customTheme,
-  clearTheme,
-  applyTheme,
-  ...props
-}: PaginationPrevButtonProps) {
-  const provider = useThemeProvider();
-  const theme = useResolveTheme(
-    [paginationTheme, provider.theme?.pagination, customTheme],
-    [get(provider.clearTheme, "pagination"), clearTheme],
-    [get(provider.applyTheme, "pagination"), applyTheme],
-  );
-
-  const mergedClassName = twMerge(disabled && theme.pages.selector.disabled, className);
-
-  if ("href" in props && props.href && !disabled) {
-    const { href, ...anchorProps } = props;
+export const PaginationNavigation = forwardRef<HTMLButtonElement | HTMLAnchorElement, PaginationPrevButtonProps>(
+  ({ children, className, disabled = false, theme: customTheme, clearTheme, applyTheme, ...props }, ref) => {
+    const provider = useThemeProvider();
+    const theme = useResolveTheme(
+      [paginationTheme, provider.theme?.pagination, customTheme],
+      [get(provider.clearTheme, "pagination"), clearTheme],
+      [get(provider.applyTheme, "pagination"), applyTheme],
+    );
+
+    const mergedClassName = twMerge(disabled && theme.pages.selector.disabled, className);
+
+    if ("href" in props && props.href && !disabled) {
+      const { href, ...anchorProps } = props;
+      return (
+        <a ref={ref as Ref<HTMLAnchorElement>} href={href} className={mergedClassName} {...anchorProps}>
+          {children}
+        </a>
+      );
+    }
+
+    const { href: _, ...buttonProps } = props as PaginationNavigationAsButton;
     return (
-      <a href={href} className={mergedClassName} {...anchorProps}>
+      <button
+        ref={ref as Ref<HTMLButtonElement>}
+        type="button"
+        className={mergedClassName}
+        disabled={disabled}
+        {...buttonProps}
+      >
         {children}
-      </a>
+      </button>
     );
-  }
-
-  const { href: _, ...buttonProps } = props as PaginationNavigationAsButton;
-  return (
-    <button type="button" className={mergedClassName} disabled={disabled} {...buttonProps}>
-      {children}
-    </button>
-  );
-}
+  },
+);
 
 PaginationNavigation.displayName = "PaginationNavigation";

From e54c423d3f8f324e6221cac8d41bce95f9f6c55f Mon Sep 17 00:00:00 2001
From: seojcarlos <jcarlos@convertiam.com>
Date: Mon, 6 Apr 2026 01:06:29 +0200
Subject: [PATCH 5/5] refactor(pagination): enforce navigation props via
 discriminated union

- Use discriminated union for DefaultPaginationProps: either
  onPageChange (client-side) or getPageUrl (anchor-based) must be
  provided, preventing misconfiguration at compile time
- Export PaginationNavigation type alias and PaginationNavigationAsAnchor
  to fix type re-export from index.ts
---
 .../src/components/Pagination/Pagination.tsx  | 33 +++++++++++++------
 .../Pagination/PaginationButton.tsx           | 11 +++++--
 2 files changed, 32 insertions(+), 12 deletions(-)

diff --git a/packages/ui/src/components/Pagination/Pagination.tsx b/packages/ui/src/components/Pagination/Pagination.tsx
index 954ae6fac4..173b993585 100644
--- a/packages/ui/src/components/Pagination/Pagination.tsx
+++ b/packages/ui/src/components/Pagination/Pagination.tsx
@@ -48,27 +48,40 @@ export interface BasePaginationProps extends ComponentProps<"nav">, ThemingProps
   layout?: "navigation" | "pagination" | "table";
   currentPage: number;
   nextLabel?: string;
-  /**
-   * Callback fired when a page is selected. Required when `getPageUrl` is not provided.
-   * When `getPageUrl` is provided, this is optional — if omitted, the anchor links handle
-   * navigation natively without client-side routing.
-   */
-  onPageChange?: (page: number) => void;
   previousLabel?: string;
   showIcons?: boolean;
 }
 
-export interface DefaultPaginationProps extends BasePaginationProps {
+interface DefaultPaginationSharedProps extends BasePaginationProps {
   layout?: "navigation" | "pagination";
+  renderPaginationButton?: (props: PaginationButtonProps) => ReactNode;
+  totalPages: number;
+}
+
+/**
+ * Client-side pagination: uses `onPageChange` callback for navigation.
+ */
+interface ClientSidePaginationProps extends DefaultPaginationSharedProps {
+  onPageChange: (page: number) => void;
+  getPageUrl?: never;
+}
+
+/**
+ * Anchor-based pagination: uses `getPageUrl` to render `<a>` elements for SEO.
+ * `onPageChange` is optional — if omitted, anchor links handle navigation natively.
+ */
+interface AnchorPaginationProps extends DefaultPaginationSharedProps {
   /**
    * A function that returns a URL for a given page number. When provided, pagination buttons
    * render as `<a>` elements instead of `<button>` elements, improving SEO by making
    * pagination links crawlable by search engines.
    */
-  getPageUrl?: (page: number) => string;
-  renderPaginationButton?: (props: PaginationButtonProps) => ReactNode;
-  totalPages: number;
+  getPageUrl: (page: number) => string;
+  onPageChange?: (page: number) => void;
 }
+
+export type DefaultPaginationProps = ClientSidePaginationProps | AnchorPaginationProps;
+
 export interface TablePaginationProps extends BasePaginationProps {
   layout: "table";
   onPageChange: (page: number) => void;
diff --git a/packages/ui/src/components/Pagination/PaginationButton.tsx b/packages/ui/src/components/Pagination/PaginationButton.tsx
index 7a5a0ac48e..9a5340cdaf 100644
--- a/packages/ui/src/components/Pagination/PaginationButton.tsx
+++ b/packages/ui/src/components/Pagination/PaginationButton.tsx
@@ -43,12 +43,19 @@ type PaginationNavigationAsButton = PaginationNavigationBaseProps &
     href?: never;
   };
 
-type PaginationNavigationAsAnchor = PaginationNavigationBaseProps &
+export type PaginationNavigationAsAnchor = PaginationNavigationBaseProps &
   Omit<ComponentProps<"a">, keyof PaginationNavigationBaseProps> & {
     href: string;
   };
 
-export type PaginationPrevButtonProps = PaginationNavigationAsButton | PaginationNavigationAsAnchor;
+/**
+ * Union type for PaginationNavigation props — used as the re-exported
+ * `PaginationNavigation` type in index.ts for consumers who need the type
+ * (not the component).
+ */
+export type PaginationNavigation = PaginationNavigationAsButton | PaginationNavigationAsAnchor;
+
+export type PaginationPrevButtonProps = PaginationNavigation;
 
 export const PaginationButton = forwardRef<HTMLButtonElement | HTMLAnchorElement, PaginationButtonProps>(
   ({ active, children, className, theme: customTheme, clearTheme, applyTheme, ...props }, ref) => {