Pagination

Usage

import { GlPagination } from "gitlab-ui-react/pagination";
import { GlKeysetPagination } from "gitlab-ui-react/keyset-pagination";

<GlPagination perPage={20} totalItems={100} value={1} />

Default

Use offset pagination when the total size is known and users benefit from jumping to a numbered page. Update value through onValueChange for button-like navigation, or provide linkGen for real page URLs.

import { useState } from "react";
import { GlPagination } from "gitlab-ui-react/pagination";

export default function PaginationExample() {
  const [page, setPage] = useState(3);

  return (
    <GlPagination
      perPage={10}
      totalItems={200}
      value={page}
      onValueChange={setPage} />
  );
}

Keyset pagination

Use keyset pagination for cursor-based data that can change while the user moves through it. It provides only Previous and Next controls and passes the relevant cursor to each callback.

import { useState } from "react";
import { GlKeysetPagination } from "gitlab-ui-react/keyset-pagination";

export default function KeysetPaginationExample() {
  const [page, setPage] = useState(1);

  return (
    <GlKeysetPagination
      endCursor={`page-${page}`}
      hasNextPage={page < 4}
      hasPreviousPage={page > 1}
      startCursor={`page-${page}`}
      onNext={() => setPage((current) => current + 1)}
      onPrevious={() => setPage((current) => current - 1)} />
  );
}

Accessibility

• Give each pagination landmark a localized and descriptive labelNav or navigationLabel, especially when more than one appears on a page.
• Keep page and control labels localized. Numbered pagination marks the active link with aria-current="page" automatically.
• After loading a new page, move focus and scroll position to the start of the updated content when appropriate.
• Prefer links with real destinations when each page has a stable URL.

API

Both components forward supported attributes to the rendered <nav> element.

GlPagination

GlKeysetPagination

Related resources

• Pagination in the Pajamas Design System
• Pagination stories in Storybook
• Keyset pagination stories in Storybook
• Pagination source and complete TypeScript props
• Keyset pagination source and complete TypeScript props