diff --git a/packages/documentation-site/patternfly-docs/content/components/pagination/img/bottom-pagination.svg b/packages/documentation-site/patternfly-docs/content/components/pagination/img/bottom-pagination.svg new file mode 100644 index 0000000000..f17fdf1c84 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/components/pagination/img/bottom-pagination.svg @@ -0,0 +1,64 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/components/pagination/img/full-pagination.svg b/packages/documentation-site/patternfly-docs/content/components/pagination/img/full-pagination.svg new file mode 100644 index 0000000000..54ff0a2ec0 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/components/pagination/img/full-pagination.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/components/pagination/img/indeterminate-pagination.svg b/packages/documentation-site/patternfly-docs/content/components/pagination/img/indeterminate-pagination.svg index 5dc4822544..88a1ec5d68 100644 --- a/packages/documentation-site/patternfly-docs/content/components/pagination/img/indeterminate-pagination.svg +++ b/packages/documentation-site/patternfly-docs/content/components/pagination/img/indeterminate-pagination.svg @@ -1,18 +1,17 @@ - - + + - - + + - - - + + diff --git a/packages/documentation-site/patternfly-docs/content/components/pagination/img/mobile-pagination.svg b/packages/documentation-site/patternfly-docs/content/components/pagination/img/mobile-pagination.svg index 85fec1afe5..41a5503b9f 100644 --- a/packages/documentation-site/patternfly-docs/content/components/pagination/img/mobile-pagination.svg +++ b/packages/documentation-site/patternfly-docs/content/components/pagination/img/mobile-pagination.svg @@ -2,7 +2,7 @@ - + @@ -11,10 +11,10 @@ - + - + @@ -30,20 +30,17 @@ - - - - - - - + + + + - + - + @@ -52,16 +49,16 @@ - + - - + + - + @@ -70,16 +67,16 @@ - + - - + + - + @@ -88,26 +85,40 @@ - + - - - - + + + + + + + + + + + + + - - - - - - + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/components/pagination/img/toolbar-pagination.svg b/packages/documentation-site/patternfly-docs/content/components/pagination/img/toolbar-pagination.svg index ccef717a7a..adf564a1cc 100644 --- a/packages/documentation-site/patternfly-docs/content/components/pagination/img/toolbar-pagination.svg +++ b/packages/documentation-site/patternfly-docs/content/components/pagination/img/toolbar-pagination.svg @@ -1,63 +1,80 @@ + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + - - + + - - + + + + - + - - - - - - - - + + + + + + + + + - - - - - - + + + + + + - + - - - - - - - - - - - - - - - + @@ -68,5 +85,11 @@ + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/components/pagination/pagination.md b/packages/documentation-site/patternfly-docs/content/components/pagination/pagination.md index c2df88f7d8..3ae622bf7b 100644 --- a/packages/documentation-site/patternfly-docs/content/components/pagination/pagination.md +++ b/packages/documentation-site/patternfly-docs/content/components/pagination/pagination.md @@ -6,65 +6,90 @@ section: components import '../components.css'; ## Usage -Add pagination above and below content views so that users can easily navigate as they read through listed items on a page. +Pagination allows users to conveniently navigate through content-dense components or page elements.
![a full page demo with a table and a pagination component within a toolbar.](./img/pagination-elements.svg)
-1. **Top pagination:** Always right-align pagination in the top toolbar, above content views. +1. **Top pagination:** Placed above the component it controls and aligned to the right. + +2. **Bottom pagination:** Placed directly after the component it controls. On desktop, bottom pagination is right-aligned by default. On mobile, bottom pagination is center-aligned and sticky by default. + +To make either top or bottom pagination sticky, so that it remains in view as users scroll through long content, refer to the [React sticky pagination](/components/pagination#sticky) or [HTML sticky pagination](/components/pagination/html#bottom-sticky) examples for implementation guidance. -2. **Bottom pagination:** Right-align pagination below content views, too. If you want the bottom pagination to be sticky so it does not scroll off the page when the content is taller that the viewport, place the pagination in a footer page section and apply the `pf-m-sticky-bottom` modifier section to -create a sticky page footer. ## Variations + +There are 3 pagination variations you can choose from, depending on your use case: +- [Full pagination:](#full-pagination) The default component to use for most desktop views when space is not a major constraint. +- [Compact pagination:](#compact-pagination) Used for narrow spaces or as the primary control for mobile views. +- [Indeterminate pagination:](#indeterminate-pagination) Used when the total number of items is unknown. + ### Full pagination -Use full pagination unless you're restricted to a narrow workspace, then use compact pagination. Full pagination occupies more toolbar territory, so you'll have limited room for other items like bulk selectors, buttons, filters, or input fields. +
+![Annotations for each element of a full pagination.](./img/full-pagination.svg) +
-[Overflow menus](/components/toolbar/design-guidelines#overflow-menu) allow you to incorporate these toolbar actions using less horizontal space. Toolbar actions automatically form into an overflow menu at specific breaking points. Learn how to customize these breakpoints in our [Toolbar](/components/toolbar/design-guidelines) documentation. +1. **Per-page selector:** Used to choose the number of items displayed on a single page at once. +2. **First page/last page:** Used to jump to the first or last page of content. +3. **Previous page/next page:** Used to navigate back or forward one page of content at a time. +4. **Current page (interactive):** Displays the current location and the total number of pages of content. Users can also manually type in a page number to jump to a desired location. -Desktop and mobile views connect with the same breakpoint specifications. On mobile, full pagination condenses to an item count. As a toolbar item, you can add and keep the item count in two ways: in both desktop and mobile views, or just in mobile view. +Full pagination contains a variety of controls that can be used to navigate the linked component, like a table or card view. This is the default recommendation, unless you're restricted in space or for use on mobile devices, in which case you should use [compact pagination](#compact-pagination) instead. -#### Desktop full pagination in toolbar +### Compact pagination
-![an example of a desktop pagination component within a toolbar.](./img/toolbar-pagination.svg) +![Example of a compact pagination.](./img/compact-pagination.svg)
-1. **Items in view:** Allows the user to select the item count (number of listed items) per page. +1. **Per-page selector:** Used to choose the number of items displayed on a single page at once. +2. **Previous page/next page:** Used to navigate back or forward one page of content at a time. -2. **Full pager:** Supplies all necessary pagination options including page-back and page-forward, page-first and page-last, and a manual option to type in a desired page number. +Compact pagination reduces visual crowding and saves space for additional actions in limited spaces, like toolbars. -#### Mobile full pagination in toolbar +### Indeterminate pagination + +When it's difficult to calculate the total number of items or page count upfront, you can use an indeterminate pagination, which replaces the total page number in the per-page selector with a general label of “many”. Users can still choose the number of items shown at once, and the indeterminate label can be used within both full and compact pagination.
-![Example of pagination on mobile table view.](./img/mobile-pagination.svg) +![Example of an indeterminate pagination.](./img/indeterminate-pagination.svg)
-1. **Items in view:** At this screen size, the top toolbar only shows the item count to indicate items currently in view. It hides all other pagination controls. +## Placement -2. **Full pager:** Supplies the same pagination options as the desktop full pager, but in the bottom toolbar. +### Desktop -### Compact pagination +For desktop views, place [full pagination](#full-pagination) above the content it controls ("top pagination"), typically within a toolbar. + +
+![an example of a desktop pagination component within a toolbar.](./img/toolbar-pagination.svg) +
-Compact pagination fits more actions into top toolbars with limited space. Choose this compact variation when your top toolbar contains many items or looks overcrowded. As with full pagination, the compact variation condenses to an item count for mobile views. +When used in a toolbar, pagination may leave limited room for other items like filters or bulk selectors. These additional items should automatically move into an [overflow menu](/components/toolbar/design-guidelines#overflow-menu) as needed. -#### Desktop compact pagination in toolbar +Also place full pagination below the component it controls ("bottom pagination").
-![Example of a compact pagination.](./img/compact-pagination.svg) +![an example of a bottom pagination component placed after a table.](./img/bottom-pagination.svg)
-1. **Items in view:** Allows the user to select the item count (number of listed items) per page, as seen in full pagination. +Bottom pagination lets users easily navigate lengthy datasets without scrolling back to the top, while ensuring that pagination adapts appropriately when switching from desktop to mobile. -2. **Compact pager:** Supplies the user with page-back and page-next controls only. +### Mobile -### Indeterminate pagination - -Use indeterminate pagination if it’s difficult to calculate the total number of items or page count upfront. In these cases, you may use “many” instead of the usual page count that would appear. +On mobile, pagination adapts in order to better conserve space. When switching from desktop to mobile, top pagination will collapse to a pagination summary with an item count and bottom pagination will adapt to a more compact design.
-![Example of a indeterminate pagination.](./img/indeterminate-pagination.svg) +![Example of pagination on mobile table view.](./img/mobile-pagination.svg)
-The text indicator provides the user with a control that displays indeterminate page count or items. +1. **Pagination summary:** A non-interactive count of items currently displayed. + +2. **Bottom pagination:** When bottom pagination shrinks in size for mobile, it becomes more compact, with a previous page, next page, and a per-page selector that allows users to choose the number of items shown at once. There are no first-page and last-page controls for bottom pagination on mobile. + +When using pagination in mobile views, follow these best practices: +- Use a top-pagination summary and bottom pagination. +- Only use full pagination for top navigation on mobile when you can't use bottom pagination, or when you can only use the bottom-pagination summary (instead of a full bottom pagination). +- Never use full pagination for both the top and bottom pagination on mobile. \ No newline at end of file