Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve Pagination docs page and block examples (#1659)

rubyycheungff598e49fa72
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationCompactPagination.doc.mjs b/packages/cli/templates/blocks/components/Pagination/PaginationCompactPagination.doc.mjs
deleted file mode 100644
index 9583a0cf5f..0000000000
--- a/packages/cli/templates/blocks/components/Pagination/PaginationCompactPagination.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Pagination — Compact Variant',
- description:
- 'Minimal pagination showing "Page X of Y" with previous/next controls.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Pagination'],
-};
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationCompactPagination.tsx b/packages/cli/templates/blocks/components/Pagination/PaginationCompactPagination.tsx
deleted file mode 100644
index 8e1b4f52a9..0000000000
--- a/packages/cli/templates/blocks/components/Pagination/PaginationCompactPagination.tsx
+++ /dev/null
@@ -1,16 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSPagination} from '@xds/core/Pagination';
-
-export default function PaginationCompactPagination() {
- const [page, setPage] = useState(1);
- return (
- <XDSPagination
- page={page}
- onChange={setPage}
- totalPages={10}
- variant="compact"
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationCountPagination.doc.mjs b/packages/cli/templates/blocks/components/Pagination/PaginationCountPagination.doc.mjs
deleted file mode 100644
index f0a4870b47..0000000000
--- a/packages/cli/templates/blocks/components/Pagination/PaginationCountPagination.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Pagination — Count Variant',
- description:
- 'Pagination showing item count (e.g. "1–20 of 200") instead of page numbers.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Pagination'],
-};
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationCountPagination.tsx b/packages/cli/templates/blocks/components/Pagination/PaginationCountPagination.tsx
deleted file mode 100644
index e945ab1568..0000000000
--- a/packages/cli/templates/blocks/components/Pagination/PaginationCountPagination.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSPagination} from '@xds/core/Pagination';
-
-export default function PaginationCountPagination() {
- const [page, setPage] = useState(1);
- return (
- <XDSPagination
- page={page}
- onChange={setPage}
- totalItems={200}
- pageSize={20}
- variant="count"
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationDotsCarousel.doc.mjs b/packages/cli/templates/blocks/components/Pagination/PaginationDotsCarousel.doc.mjs
new file mode 100644
index 0000000000..8fcd656c1d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Pagination/PaginationDotsCarousel.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Pagination — Dots Carousel',
+ description:
+ 'A review carousel using dot pagination to step through testimonial cards. Use the dots variant for carousels, galleries, and any paged content where the total is small and visible position matters more than a page number.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Pagination', 'Card', 'Text', 'Layout', 'Icon', 'Avatar'],
+};
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationDotsCarousel.tsx b/packages/cli/templates/blocks/components/Pagination/PaginationDotsCarousel.tsx
new file mode 100644
index 0000000000..3b6a4ebdd2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Pagination/PaginationDotsCarousel.tsx
@@ -0,0 +1,101 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSPagination} from '@xds/core/Pagination';
+import {XDSCard} from '@xds/core/Card';
+import {XDSText} from '@xds/core/Text';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSIcon} from '@xds/core/Icon';
+import {StarIcon} from '@heroicons/react/24/solid';
+import * as stylex from '@stylexjs/stylex';
+
+const REVIEWS = [
+ {
+ name: 'Jeannie Grant',
+ date: 'June 01, 2025',
+ stars: 5,
+ quote:
+ 'A thorough report was done on our financial situation. Better deals were found and processed on our behalf, which took a lot of stress away.',
+ },
+ {
+ name: 'Derval Russell',
+ date: 'November 09, 2025',
+ stars: 5,
+ quote:
+ 'I have been a client for 8 years now and have always found the advice provided excellent. They take the time to explain things clearly.',
+ },
+ {
+ name: 'Claire Dawson',
+ date: 'October 15, 2025',
+ stars: 5,
+ quote:
+ 'Constantly professional and concise. Our mortgage process was smooth from start to finish thanks to their dedicated team.',
+ },
+ {
+ name: 'Marcus Webb',
+ date: 'September 22, 2025',
+ stars: 4,
+ quote:
+ 'Great service overall. The team was responsive and knowledgeable. Would definitely recommend to anyone looking for solid financial advice.',
+ },
+];
+
+const styles = stylex.create({
+ root: {
+ maxWidth: 480,
+ width: '100%',
+ },
+ pagination: {
+ justifyContent: 'center',
+ paddingTop: 4,
+ },
+});
+
+function Stars({count}: {count: number}) {
+ return (
+ <XDSStack direction="horizontal" gap={0}>
+ {Array.from({length: count}, (_, i) => (
+ <XDSIcon key={i} icon={StarIcon} size="sm" color="warning" />
+ ))}
+ </XDSStack>
+ );
+}
+
+export default function PaginationDotsCarousel() {
+ const [page, setPage] = useState(1);
+ const review = REVIEWS[page - 1];
+
+ return (
+ <XDSStack direction="vertical" gap={3} xstyle={styles.root}>
+ <XDSCard padding={5}>
+ <XDSStack direction="vertical" gap={3}>
+ <Stars count={review.stars} />
+ <XDSText type="body">{review.quote}</XDSText>
+ <XDSStack
+ direction="horizontal"
+ gap={3}
+ vAlign="center"
+ hAlign="start">
+ <XDSAvatar name={review.name} size="small" />
+ <XDSStack direction="vertical" gap={0}>
+ <XDSText type="supporting" weight="bold">
+ {review.name}
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ {review.date}
+ </XDSText>
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ </XDSCard>
+ <XDSPagination
+ page={page}
+ onChange={setPage}
+ totalPages={REVIEWS.length}
+ variant="dots"
+ xstyle={styles.pagination}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationDotsPagination.doc.mjs b/packages/cli/templates/blocks/components/Pagination/PaginationDotsPagination.doc.mjs
deleted file mode 100644
index 7ae0795c8f..0000000000
--- a/packages/cli/templates/blocks/components/Pagination/PaginationDotsPagination.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Pagination — Dots Variant',
- description:
- 'Pagination using dot indicators for page position, suited for carousels and slideshows.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Pagination'],
-};
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationDotsPagination.tsx b/packages/cli/templates/blocks/components/Pagination/PaginationDotsPagination.tsx
deleted file mode 100644
index 2d229b40e1..0000000000
--- a/packages/cli/templates/blocks/components/Pagination/PaginationDotsPagination.tsx
+++ /dev/null
@@ -1,16 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSPagination} from '@xds/core/Pagination';
-
-export default function PaginationDotsPagination() {
- const [page, setPage] = useState(1);
- return (
- <XDSPagination
- page={page}
- onChange={setPage}
- totalPages={8}
- variant="dots"
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationPageSize.doc.mjs b/packages/cli/templates/blocks/components/Pagination/PaginationPageSize.doc.mjs
new file mode 100644
index 0000000000..6fd481d2da
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Pagination/PaginationPageSize.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Pagination — Page Size Selector',
+ description:
+ 'A transactions table with pagination and a page size dropdown at the bottom. Shows how pagination works as a footer below real content, with adjustable rows per page.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Pagination', 'Text', 'Layout', 'Table'],
+};
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationPageSize.tsx b/packages/cli/templates/blocks/components/Pagination/PaginationPageSize.tsx
new file mode 100644
index 0000000000..259462bb31
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Pagination/PaginationPageSize.tsx
@@ -0,0 +1,65 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSPagination} from '@xds/core/Pagination';
+import {XDSHeading} from '@xds/core/Text';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSTable} from '@xds/core/Table';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ root: {
+ width: '100%',
+ },
+ pagination: {
+ paddingTop: 8,
+ flexDirection: 'row-reverse',
+ },
+});
+
+const DATA = [
+ {
+ id: '1',
+ date: 'Apr 18',
+ description: 'Payment received',
+ amount: '$2,450.00',
+ },
+ {
+ id: '2',
+ date: 'Apr 15',
+ description: 'Subscription renewal',
+ amount: '$99.00',
+ },
+ {id: '3', date: 'Apr 12', description: 'Refund issued', amount: '-$180.00'},
+ {id: '4', date: 'Apr 10', description: 'Invoice paid', amount: '$1,200.00'},
+];
+
+export default function PaginationPageSize() {
+ const [page, setPage] = useState(1);
+ const [pageSize, setPageSize] = useState(10);
+
+ return (
+ <XDSStack direction="vertical" xstyle={styles.root}>
+ <XDSHeading level={4}>Transactions</XDSHeading>
+ <XDSTable
+ idKey="id"
+ columns={[
+ {key: 'date', header: 'Date'},
+ {key: 'description', header: 'Description'},
+ {key: 'amount', header: 'Amount'},
+ ]}
+ data={DATA}
+ />
+ <XDSPagination
+ page={page}
+ onChange={setPage}
+ totalItems={350}
+ pageSize={pageSize}
+ onPageSizeChange={setPageSize}
+ pageSizeOptions={[10, 25, 50, 100]}
+ variant="count"
+ xstyle={styles.pagination}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationShowcase.doc.mjs b/packages/cli/templates/blocks/components/Pagination/PaginationShowcase.doc.mjs
deleted file mode 100644
index e69d7a5775..0000000000
--- a/packages/cli/templates/blocks/components/Pagination/PaginationShowcase.doc.mjs
+++ /dev/null
@@ -1,8 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Pagination',
- isReady: true,
- aspectRatio: 1,
- isShowcase: true,
-};
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationShowcase.tsx b/packages/cli/templates/blocks/components/Pagination/PaginationShowcase.tsx
deleted file mode 100644
index 970b011090..0000000000
--- a/packages/cli/templates/blocks/components/Pagination/PaginationShowcase.tsx
+++ /dev/null
@@ -1,12 +0,0 @@
-import {XDSPagination} from '@xds/core/Pagination';
-
-export default function PaginationShowcase() {
- return (
- <XDSPagination
- page={1}
- onChange={() => {}}
- totalItems={100}
- pageSize={10}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationVariants.doc.mjs b/packages/cli/templates/blocks/components/Pagination/PaginationVariants.doc.mjs
new file mode 100644
index 0000000000..bed6158567
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Pagination/PaginationVariants.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Pagination — Variants',
+ description:
+ 'All four display variants stacked — dots, compact, count, and pages. A quick visual reference for choosing the right variant.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Pagination', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationVariants.tsx b/packages/cli/templates/blocks/components/Pagination/PaginationVariants.tsx
new file mode 100644
index 0000000000..def70c1524
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Pagination/PaginationVariants.tsx
@@ -0,0 +1,50 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSPagination} from '@xds/core/Pagination';
+import {XDSStack} from '@xds/core/Layout';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ root: {
+ width: '100%',
+ },
+});
+
+export default function PaginationVariants() {
+ const [pagesPage, setPagesPage] = useState(3);
+ const [countPage, setCountPage] = useState(2);
+ const [compactPage, setCompactPage] = useState(5);
+ const [dotsPage, setDotsPage] = useState(3);
+
+ return (
+ <XDSStack direction="vertical" gap={5} hAlign="center" xstyle={styles.root}>
+ <XDSPagination
+ page={dotsPage}
+ onChange={setDotsPage}
+ totalPages={8}
+ variant="dots"
+ />
+ <XDSPagination
+ page={compactPage}
+ onChange={setCompactPage}
+ totalPages={10}
+ variant="compact"
+ />
+ <XDSPagination
+ page={countPage}
+ onChange={setCountPage}
+ totalItems={200}
+ pageSize={20}
+ variant="count"
+ />
+ <XDSPagination
+ page={pagesPage}
+ onChange={setPagesPage}
+ totalItems={200}
+ pageSize={10}
+ variant="pages"
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationWithPageSize.doc.mjs b/packages/cli/templates/blocks/components/Pagination/PaginationWithPageSize.doc.mjs
deleted file mode 100644
index 6d559dd6a0..0000000000
--- a/packages/cli/templates/blocks/components/Pagination/PaginationWithPageSize.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Pagination — With Page Size',
- description:
- 'Pagination with a page-size selector dropdown for adjustable rows per page.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Pagination'],
-};
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationWithPageSize.tsx b/packages/cli/templates/blocks/components/Pagination/PaginationWithPageSize.tsx
deleted file mode 100644
index fad4707fdc..0000000000
--- a/packages/cli/templates/blocks/components/Pagination/PaginationWithPageSize.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSPagination} from '@xds/core/Pagination';
-
-export default function PaginationWithPageSize() {
- const [page, setPage] = useState(1);
- const [pageSize, setPageSize] = useState(10);
- return (
- <XDSPagination
- page={page}
- onChange={setPage}
- totalItems={200}
- pageSize={pageSize}
- onPageSizeChange={setPageSize}
- pageSizeOptions={[10, 20, 50]}
- variant="count"
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationWithTable.doc.mjs b/packages/cli/templates/blocks/components/Pagination/PaginationWithTable.doc.mjs
new file mode 100644
index 0000000000..b28d06d4c2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Pagination/PaginationWithTable.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Pagination — With Table',
+ description:
+ 'Pagination below a data table with client-side page slicing. Use the count variant with small size for dense data views where users need to see item ranges.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Pagination', 'Table', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Pagination/PaginationWithTable.tsx b/packages/cli/templates/blocks/components/Pagination/PaginationWithTable.tsx
new file mode 100644
index 0000000000..e8d4b0fd88
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Pagination/PaginationWithTable.tsx
@@ -0,0 +1,63 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSPagination} from '@xds/core/Pagination';
+import {XDSTable} from '@xds/core/Table';
+import {XDSStack} from '@xds/core/Layout';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ root: {
+ width: '100%',
+ },
+ pagination: {
+ justifyContent: 'center',
+ paddingTop: 8,
+ },
+});
+
+const ALL_DATA = [
+ {id: '1', name: 'Olivia Chen', role: 'Engineer', status: 'Active'},
+ {id: '2', name: 'Marcus Rivera', role: 'Designer', status: 'Active'},
+ {id: '3', name: 'Aisha Patel', role: 'Marketing', status: 'Invited'},
+ {id: '4', name: 'James Okafor', role: 'Engineer', status: 'Active'},
+ {id: '5', name: 'Sofia Nguyen', role: 'Sales', status: 'Active'},
+ {id: '6', name: 'Liam Johansson', role: 'Engineer', status: 'Inactive'},
+ {id: '7', name: 'Elena Kowalski', role: 'Designer', status: 'Active'},
+ {id: '8', name: 'David Kim', role: 'Marketing', status: 'Active'},
+ {id: '9', name: 'Priya Sharma', role: 'Sales', status: 'Invited'},
+ {id: '10', name: 'Noah Tanaka', role: 'Engineer', status: 'Active'},
+ {id: '11', name: 'Fatima Al-Rashid', role: 'Designer', status: 'Active'},
+ {id: '12', name: 'Carlos Mendez', role: 'Marketing', status: 'Inactive'},
+];
+
+const PAGE_SIZE = 4;
+
+export default function PaginationWithTable() {
+ const [page, setPage] = useState(1);
+ const start = (page - 1) * PAGE_SIZE;
+ const pageData = ALL_DATA.slice(start, start + PAGE_SIZE);
+
+ return (
+ <XDSStack direction="vertical" xstyle={styles.root}>
+ <XDSTable
+ idKey="id"
+ columns={[
+ {key: 'name', header: 'Name'},
+ {key: 'role', header: 'Role'},
+ {key: 'status', header: 'Status'},
+ ]}
+ data={pageData}
+ />
+ <XDSPagination
+ page={page}
+ onChange={setPage}
+ totalItems={ALL_DATA.length}
+ pageSize={PAGE_SIZE}
+ variant="count"
+ size="sm"
+ xstyle={styles.pagination}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjs
index 2b084fbcc2..0b9be67696 100644
--- a/packages/core/src/Pagination/Pagination.doc.mjs
+++ b/packages/core/src/Pagination/Pagination.doc.mjs
@@ -105,12 +105,16 @@ export const docs = {
},
usage: {
description:
- 'Pagination provides controls for navigating through pages of content. Use it to break large data sets into manageable pages, supporting multiple display variants for different density needs.',
+ 'Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context — numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.',
bestPractices: [
- { guidance: true, description: 'Choose the variant that best matches the information density of your layout — page numbers for precise navigation, dots for carousels.' },
- { guidance: true, description: 'Provide totalItems or totalPages when the total is known so users can see how much content remains.' },
- { guidance: false, description: 'Show Pagination when all items fit on a single page.' },
- { guidance: false, description: 'Mix different Pagination variants within the same view.' },
+ { guidance: true, description: 'Place pagination below the content it controls so users see results before navigating.' },
+ { guidance: true, description: 'Use the pages variant for data tables where users need to jump to a specific page.' },
+ { guidance: true, description: 'Use the count variant with a page size selector when users need to control how many items they see at once.' },
+ { guidance: true, description: 'Use the dots variant for carousels and walkthroughs where the total is small and position matters more than a number.' },
+ { guidance: true, description: 'Pass totalItems when the total is known so users can see how much content remains.' },
+ { guidance: false, description: 'Show pagination when all items fit on a single page — there is nothing to paginate.' },
+ { guidance: false, description: 'Use the dots variant for more than about 10 pages — the dots become too small to be useful.' },
+ { guidance: false, description: 'Place pagination above the content — users expect it at the bottom.' },
],
},
};
@@ -220,12 +224,16 @@ export const docsZh = {
},
usage: {
description:
- 'Pagination provides controls for navigating through pages of content. Use it to break large data sets into manageable pages, supporting multiple display variants for different density needs.',
+ 'Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context — numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.',
bestPractices: [
- { guidance: true, description: 'Choose the variant that best matches the information density of your layout — page numbers for precise navigation, dots for carousels.' },
- { guidance: true, description: 'Provide totalItems or totalPages when the total is known so users can see how much content remains.' },
- { guidance: false, description: 'Show Pagination when all items fit on a single page.' },
- { guidance: false, description: 'Mix different Pagination variants within the same view.' },
+ { guidance: true, description: 'Place pagination below the content it controls so users see results before navigating.' },
+ { guidance: true, description: 'Use the pages variant for data tables where users need to jump to a specific page.' },
+ { guidance: true, description: 'Use the count variant with a page size selector when users need to control how many items they see at once.' },
+ { guidance: true, description: 'Use the dots variant for carousels and walkthroughs where the total is small and position matters more than a number.' },
+ { guidance: true, description: 'Pass totalItems when the total is known so users can see how much content remains.' },
+ { guidance: false, description: 'Show pagination when all items fit on a single page — there is nothing to paginate.' },
+ { guidance: false, description: 'Use the dots variant for more than about 10 pages — the dots become too small to be useful.' },
+ { guidance: false, description: 'Place pagination above the content — users expect it at the bottom.' },
],
},
};
@@ -236,12 +244,16 @@ export const docsDense = {
'Standalone pagination controls for navigating content pages. Supports multiple display variants + works w/ known totals or cursor-based pagination.',
usage: {
description:
- 'Pagination provides controls for navigating through pages of content. Use it to break large data sets into manageable pages, supporting multiple display variants for different density needs.',
+ 'Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context — numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.',
bestPractices: [
- { guidance: true, description: 'Choose the variant that best matches the information density of your layout — page numbers for precise navigation, dots for carousels.' },
- { guidance: true, description: 'Provide totalItems or totalPages when the total is known so users can see how much content remains.' },
- { guidance: false, description: 'Show Pagination when all items fit on a single page.' },
- { guidance: false, description: 'Mix different Pagination variants within the same view.' },
+ { guidance: true, description: 'Place pagination below the content it controls so users see results before navigating.' },
+ { guidance: true, description: 'Use the pages variant for data tables where users need to jump to a specific page.' },
+ { guidance: true, description: 'Use the count variant with a page size selector when users need to control how many items they see at once.' },
+ { guidance: true, description: 'Use the dots variant for carousels and walkthroughs where the total is small and position matters more than a number.' },
+ { guidance: true, description: 'Pass totalItems when the total is known so users can see how much content remains.' },
+ { guidance: false, description: 'Show pagination when all items fit on a single page — there is nothing to paginate.' },
+ { guidance: false, description: 'Use the dots variant for more than about 10 pages — the dots become too small to be useful.' },
+ { guidance: false, description: 'Place pagination above the content — users expect it at the bottom.' },
],
},
propDescriptions: {