diff --git a/src/pages/components/pagination/images/pagination-usage-anatomy-nav.png b/src/pages/components/pagination/images/pagination-usage-anatomy-nav.png
new file mode 100644
index 00000000000..08547854b6d
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-anatomy-nav.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-anatomy.png b/src/pages/components/pagination/images/pagination-usage-anatomy.png
new file mode 100644
index 00000000000..d52f296e066
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-anatomy.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-clickable-areas-pagination-nav.png b/src/pages/components/pagination/images/pagination-usage-clickable-areas-pagination-nav.png
new file mode 100644
index 00000000000..54a8280e4a2
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-clickable-areas-pagination-nav.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-clickable-areas-pagination.png b/src/pages/components/pagination/images/pagination-usage-clickable-areas-pagination.png
new file mode 100644
index 00000000000..0c19a2a96c4
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-clickable-areas-pagination.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-modifier-page-naming.png b/src/pages/components/pagination/images/pagination-usage-modifier-page-naming.png
new file mode 100644
index 00000000000..83d177a71a3
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-modifier-page-naming.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-overflow-pagination-nav.png b/src/pages/components/pagination/images/pagination-usage-overflow-pagination-nav.png
new file mode 100644
index 00000000000..cb32e34f127
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-overflow-pagination-nav.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-overview-in-context.png b/src/pages/components/pagination/images/pagination-usage-overview-in-context.png
new file mode 100644
index 00000000000..b54e12f6f07
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-overview-in-context.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-pagination-in-context.png b/src/pages/components/pagination/images/pagination-usage-pagination-in-context.png
new file mode 100644
index 00000000000..06519765c16
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-pagination-in-context.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-pagination-nav-in-context.png b/src/pages/components/pagination/images/pagination-usage-pagination-nav-in-context.png
new file mode 100644
index 00000000000..89b98dfd15b
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-pagination-nav-in-context.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-placement-data-table-do.png b/src/pages/components/pagination/images/pagination-usage-placement-data-table-do.png
new file mode 100644
index 00000000000..3897d2e5fd2
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-placement-data-table-do.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-placement-data-table-dont.png b/src/pages/components/pagination/images/pagination-usage-placement-data-table-dont.png
new file mode 100644
index 00000000000..886e694624c
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-placement-data-table-dont.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-placement-pagination-nav.png b/src/pages/components/pagination/images/pagination-usage-placement-pagination-nav.png
new file mode 100644
index 00000000000..fe375aa4b94
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-placement-pagination-nav.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-placement-pagination.png b/src/pages/components/pagination/images/pagination-usage-placement-pagination.png
new file mode 100644
index 00000000000..5e0d7c36fb8
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-placement-pagination.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-responsive-behavior-pagination-nav.png b/src/pages/components/pagination/images/pagination-usage-responsive-behavior-pagination-nav.png
new file mode 100644
index 00000000000..5d27395f560
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-responsive-behavior-pagination-nav.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-responsiveness-pagination.png b/src/pages/components/pagination/images/pagination-usage-responsiveness-pagination.png
new file mode 100644
index 00000000000..7ca4db2b899
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-responsiveness-pagination.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-size-pairings.png b/src/pages/components/pagination/images/pagination-usage-size-pairings.png
new file mode 100644
index 00000000000..b13fd2836ee
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-size-pairings.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-sizes-pagination-nav.png b/src/pages/components/pagination/images/pagination-usage-sizes-pagination-nav.png
new file mode 100644
index 00000000000..7620d57e1c5
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-sizes-pagination-nav.png differ
diff --git a/src/pages/components/pagination/images/pagination-usage-sizes.png b/src/pages/components/pagination/images/pagination-usage-sizes.png
new file mode 100644
index 00000000000..799fcf49617
Binary files /dev/null and b/src/pages/components/pagination/images/pagination-usage-sizes.png differ
diff --git a/src/pages/components/pagination/usage.mdx b/src/pages/components/pagination/usage.mdx
index c441094fe5a..eec0ce65a34 100755
--- a/src/pages/components/pagination/usage.mdx
+++ b/src/pages/components/pagination/usage.mdx
@@ -1,8 +1,8 @@
---
title: Pagination
description:
- Pagination is used for splitting up content or data into several pages, with a
- control for navigating to the next or previous page.
+ Pagination splits content or data into several pages, with a control for
+ navigating to the next or previous page.
tabs: ['Usage', 'Style', 'Code', 'Accessibility']
---
@@ -10,8 +10,8 @@ import A11yStatus from 'components/A11yStatus';
-Pagination is used for splitting up content or data into several pages, with a
-control for navigating to the next or previous page.
+Pagination splits content or data into several pages, with a control for
+navigating to the next or previous page.
@@ -19,7 +19,12 @@ control for navigating to the next or previous page.
Live demo
Overview
-Best practices
+Formatting
+Content
+Pagination
+Pagination nav
+Modifiers
+Related
Feedback
@@ -54,55 +59,413 @@ control for navigating to the next or previous page.
## Overview
-Generally, pagination is used if there are more than 25 items displayed in one
-view.
+Pagination organizes and divides large amounts of content on separate pages and
+gives the user control over how much content they want to view on each page.
+Pagination can be used with a data table or on a page.
-The default number displayed will vary depending on the context.
+
+
+
+
+
+
+
+
+Example of the pagination component in a UI
+
+### When to use
+
+- When it could take a considerable amount of time to load the available data at
+ once or in a scrolling view
+- When there is too much data to display on one page or within one view of a
+ component
+- To make large amounts of data more accessible to consume by users
+- To optimize on-page real estate
+- To give users more control over how they view large amounts of information
+
+### When not to use
+
+- Do not use it to display linear journeys, for example, in a form progression.
+ Instead, use the
+ [progress bar](https://carbondesignsystem.com/components/progress-bar/usage/)
+ or [button](https://carbondesignsystem.com/components/button/usage/)
+ components to navigate forward and backward.
+- Do not use pagination superfluously, and aim to use it to improve usability or
+ performance.
+
+### Variants
+
+| Variant | Usage |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --- |
+| [Pagination](#pagination) | The pagination variant is typically connected at the bottom of the data table component to help paginate large amounts of data. |
+| [Pagination nav](#pagination-nav) | The pagination nav variant is mainly used in on-page situations to help paginate either a whole page or sections of a page. | |
+
+## Formatting
+
+### Anatomy of pagination
+
+
+
+
+
+
+
+
+
+Anatomy of the pagination variant
+
+1. **Items per page:** Shows the current number of items that appear per page.
+2. **Range of items:** Shows the current range of items and lists the total
+ amount of items.
+3. **Current page:** Shows the current page the user is on and lists the total
+ amount of pages.
+4. **Previous and next buttons:** Buttons that take you to the previous or next
+ page.
+5. **Container:** The container bar of the whole pagination component.
+
+### Anatomy of pagination nav
+
+
+
+
+
+
+
+
+
+Anatomy of the pagination nav variant
+
+1. **Unselected page button:** A page the user could select and view.
+2. **Selected page button:** The current page the user is viewing.
+3. **Overflow button:** Contains available pages that can be navigated to but
+ cannot be shown upfront in the component because of the current viewport.
+4. **Previous and next buttons:** Buttons that take you to the previous or next
+ page.
+5. **Container:** The container of the whole pagination component.
+
+### Sizing
+
+The pagination component is available in three sizes in both variants:
+**large**, **medium**, and **small**.
+
+
+
+
+
+
+
+
+
+Sizes of pagination
+
+
+
+
+
+
+
+
+
+Sizes of pagination nav
+
+### Data table size pairings
+
+We recommend using the same height pagination as you do for the data table
+component rows to which it is connected. In some cases, the height sizes of
+these two components will not be the same because we do not offer extra small
+and extra large sizes for pagination. When using the extra large data table row
+height, use the large pagination. When using the extra small data table row
+height, use the small pagination.
+
+
+
+
+
+
+
+
+
+Size pairings of the pagination and data table components
+
+### Placement
+
+Place the pagination near the related component or area of the page where the
+information will be paginated.
+
+#### Placing pagination with data table
+
+When using the pagination variant with a data table, the pagination should be
+stacked and below the table with no padding inbetween them.
+
+
+
+
+
+
+
+
+
+Placement of the pagination variant
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+#### Placing pagination nav on a page
+
+When using the pagination nav variant on a page, float it below the content to
+which it is paginating and related to. The pagination can be right aligned or
+left aligned to the content above it. When it doubt, choose right alignment.
+
+
+
+
+
+
+
+
+
+Placement of the pagination nav variant
+
+## Content
+
+### Main elements
+
+#### Label text
+
+The label text in the pagination component should be concise and instructional.
+It describes the items per page and the number of pages or items. We recommend
+not modifying the label text unless necessary for specific use cases.
+
+#### Select component option text
+
+The select components option text is shown as a number, indicating the items per
+page and the current page. Alternatively, this can be indicated as a word for
+the “Items per page” selection instead of a number.
+
+### Overflow content
+
+In the pagination nav variant, an ellipsis button appears between pages to
+indicate that there are numerous pages to navigate to within the ellipsis button
+menu. We recommend never placing the ellipsis button at the beginning or end of
+a series of pages in the pagination component.
+
+
+
+
+
+
+
+
+
+
+ Example of the ellipsis button for overflow content in the pagination nav
+ variant
+
+
+### Further guidance
+
+For further content guidance, see Carbon's
+[content guidelines](https://carbondesignsystem.com/guidelines/content/overview/).
+
+## Pagination
+
+The pagination variant is typically a bar attached to the bottom of a data table
+to paginate its data.
+
+
+
+
+
+
+
+
+
+Example of the pagination variant in a UI
+
+### States
+
+The pagination variant has the select component and ghost icon button component
+nested within it and inherits their component states. For more information on
+these states, refer to the
+[select](https://carbondesignsystem.com/components/select/style/) and
+[ghost icon button](https://carbondesignsystem.com/components/button/style/)
+style tab guidance.
+
+### Interactions
+
+#### Mouse
+
+- Clicking on the select component will open the menu and reveal options.
+- To close the menu, choose a different option or click outside the menu area.
+- Clicking on a previous or next button will navigate you to the previous or
+ next page.
+
+#### Keyboard
+
+- On focus, the select component menu is opened with pressing `Space`or with
+ `Up` or `Down` arrows which also cycle through the values.
+- Pressing `Space` or`Enter` selects a value and closes the menu.
+- The menu can be closed by pressing `Esc`.
+- The previous and next ghost icon buttons are activated by pressing `Space` or
+ `Enter`.
+
+### Responsive behavior
+
+The pagination variant retains all its content and nested components at every
+breakpoint except for the small breakpoint. The select components have been
+removed at the small breakpoint, but information on the total number of items,
+items being displayed, and previous and next buttons remain.
-## Best practices
+
+
+
+
+
+
+
+
+
+ Pagination variant responsive behavior in all breakpoints versus the small
+ breakpoint
+
+
+### Clickable areas
+
+Within the pagination variant, there are four clickable areas. Two select
+components allow you to change the number of items per page and the page number.
+Two ghost icon buttons take you to the previous or next page.
+
+
+
-#### Identify the current page
+
-Clearly identify which page the user is on by displaying the current page
-number. By providing context into how many pages there are in total (eg. 1 of 4
-pages), you can help provide clarity around the data displayed.
+
+
+
+Pagination variant clickable areas
-#### Provide various options for navigating
+## Pagination nav
-_Previous_ and _next_ chevrons or links are the most useful way for the user to
-move forward or backward through pages of data. Provide an
-[inline select](/components/select/usage) in which users can choose the page
-they wish to navigate to.
+The pagination nav variant is most commonly used to paginate full pages or
+sections of content on a page. It floats under and near the related content.
+
+
+
+
+
+
+
+
+
+Example of the pagination nav variant in a UI
+
+### States
+
+The pagination nav variant has the ghost icon button component and the
+breadcrumb overflow button component nested within it that inherits their
+component states. For more information on these states, refer to the
+[select](https://carbondesignsystem.com/components/select/style/) and
+[breadcrumb overflow button](https://carbondesignsystem.com/components/breadcrumb/style/)
+style tab guidance.
+
+### Interactions
+
+#### Mouse
+
+- Clicking on a button number will navigate you to that page.
+- Clicking on a previous or next caret button will navigate you to the previous
+ and next pages of the one you are currently viewing.
+- Clicking on an overflow ellipsis button will open a select menu to choose a
+ page to navigate to. Upon clicking on a page option from the menu, you will
+ navigate to that page.
+
+#### Keyboard
+
+- The icon button receives focus and you can move between buttons by pressing
+ the `Up` or `Down` arrows.
+- The page number buttons are activated by pressing `Space` or `Enter`.
+- The previous and next buttons are activated by pressing `Space` or `Enter`.
+
+### Responsive behavior
+
+In small screens, the pagination nav variant can provide an ellipsis button to
+indicate there are more pages to navigate to within the ellipsis button menu.
-
+
+
+ Pagination nav variant responsive behavior in large versus small breakpoints
+
+
+### Clickable areas
+
+Every button in the pagination nav variant is clickable. Two ghost icon buttons
+take you to the previous or next page. The rest of the page number buttons take
+you to that particular page.
+
-
+
-#### Items per page
+Clickable areas within the pagination nav variant
+
+## Modifiers
+
+### Page looping
+
+For the pagination nav variant, instead of turning off the previous or next
+caret buttons when you reach either the first or last page of the pagination
+component, you can enable the option to loop through the available pages
+continuously.
-Use an inline select within the pagination bar so the user can change the amount
-of data displayed per page.
+### Page naming
+
+By default, the select component option text is displayed as a number, showing
+items per page and the current page. However, we offer an alternative option to
+use a word instead of a number for the “Items per page” selection if that better
+meets your requirements.
-
+
+Select components content alternative of numbers versus words
+
+## Related
+
+- [Data table](https://carbondesignsystem.com/components/data-table/usage/)
+
## Feedback
Help us improve this component by providing feedback, asking questions, and