Pagination
Page navigation in three layouts: numbered pages, a simple page status, or a table-footer row with rows-per-page.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
variant | PaginationVariant | numbered | Layout of the controls: page numbers, a "Page 2 of 10" status, or the table-footer row. |
page | number | 1 | The page on show, 1-based. Reflected, and clamped to the available range. |
page-size | number | 10 | Items per page. Together with total-items it decides how many pages there are. |
total-items | number | 0 | Total number of items to page through. |
total-pages | number | 0 | Number of pages, when the item count is unknown. Takes precedence over total-items. |
sibling-count | number | 1 | How many page numbers are shown on each side of the current page. |
boundary-count | number | 1 | How many page numbers are always shown at each end of the range. |
page-size-options | number[] | DEFAULT_PAGE_SIZE_OPTIONS | Rows-per-page choices of the compact variant. Empty hides the select. |
hide-page-size | boolean | false | Hide the rows-per-page select of the compact variant. |
hide-range | boolean | false | Hide the range status ("21–30 of 100") of the compact variant. |
show-first-last | boolean | false | Add first-page and last-page controls around the previous/next pair. Meant for simple and compact, which show
no page numbers; in the numbered variant the pinned boundary numbers already reach both ends, unless
boundary-count is 0. |
hide-nav-labels | boolean | false | Keep the previous/next icons but drop their visible text; the accessible name is unchanged. |
disabled | boolean | false | Dim every control and ignore interaction. |
previous-label | string | Previous | Visible and accessible label of the previous-page control. |
next-label | string | Next | Visible and accessible label of the next-page control. |
first-label | string | First | Visible and accessible label of the first-page control. |
last-label | string | Last | Visible and accessible label of the last-page control. |
page-size-label | string | Rows per page: | Text before the rows-per-page select. A trailing colon is dropped from the select's accessible name. |
range-template | string | {start}–{end} of {total} | Range status of the compact variant. Placeholders: {start}, {end}, {total}. |
page-template | string | Page {page} of {pageCount} | Status of the simple variant. Placeholders: {page}, {pageCount}. |
page-label-template | string | Go to page {page} | Accessible name of a page number. Placeholder: {page}. |
jump-label-template | string | Jump to page {page}, skipping {count} pages | Accessible name of an ellipsis. Placeholders: {page} (where it jumps), {from}, {to}, {count} (pages hidden). |
aria-label | string | — | Accessible name of the navigation landmark. |
Slots
| Name | Description |
|---|---|
previous-icon | Icon of the previous-page control. Defaults to a chevron. |
next-icon | Icon of the next-page control. Defaults to a chevron. |
first-icon | Icon of the first-page control (show-first-last). Defaults to a double chevron. |
last-icon | Icon of the last-page control (show-first-last). Defaults to a double chevron. |
Events
| Name | Type | Description |
|---|---|---|
page-change | CustomEvent<PageChangeEventDetail> | Fired after the shown page changes, by a control or by a page-size change. detail.startIndex / detail.endIndex slice the items of the new page. |
page-size-change | CustomEvent<PageSizeChangeEventDetail> | Fired after the user picks another rows-per-page value. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
nav | A first, previous, next or last page button. |
item | A numbered page button. |
ellipsis | A control that jumps across a hidden range of pages. |
label | Current-page, item-range or page-size text. |
page-size | The c2-select used to change the number of items per page. |
pagination | The outer pagination navigation landmark. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-pagination--gap | pixel | 4px | Space between the controls. |
--c2-pagination--section-gap | pixel | 24px | Space between the groups of the compact variant. |
--c2-pagination--justify-content | justify-content | flex-start | Where the controls sit in the host's width. |
--c2-pagination__item--min-width | pixel | 36px | |
--c2-pagination__item--height | pixel | 36px | |
--c2-pagination__item--padding-left | padding | 8px | |
--c2-pagination__item--padding-right | padding | 8px | |
--c2-pagination__item--color | color | #18181b | |
--c2-pagination__item--background-color | color | transparent | |
--c2-pagination__item--border | border | 1px solid transparent | |
--c2-pagination__item--border-radius | border-radius | 8px | |
--c2-pagination__item--font-size | font-size | 14px | |
--c2-pagination__item--font-weight | font-weight | 500 | |
--c2-pagination__item__hover--color | color | #18181b | |
--c2-pagination__item__hover--background-color | color | #f4f4f5 | |
--c2-pagination__item__hover--border | border | 1px solid transparent | |
--c2-pagination__item__selected--color | color | #18181b | |
--c2-pagination__item__selected--background-color | color | #ffffff | |
--c2-pagination__item__selected--border | border | 1px solid #e4e4e7 | |
--c2-pagination__item__selected--font-weight | font-weight | 500 | |
--c2-pagination__item__focus--outline | outline | 2px solid rgba(2, 101, 220, 0.4) | |
--c2-pagination__item__focus--outline-offset | pixel | 1px | |
--c2-pagination__item__disabled--opacity | opacity | 0.38 | |
--c2-pagination__nav--gap | pixel | 6px | Space between a previous/next icon and its label. |
--c2-pagination__nav--padding-left | padding | 10px | |
--c2-pagination__nav--padding-right | padding | 10px | |
--c2-pagination__nav--color | color | #18181b | |
--c2-pagination__nav--background-color | color | transparent | |
--c2-pagination__nav--border | border | 1px solid transparent | |
--c2-pagination__nav--border-radius | border-radius | 8px | |
--c2-pagination__nav--font-size | font-size | 14px | |
--c2-pagination__nav--font-weight | font-weight | 500 | |
--c2-pagination__nav__hover--color | color | #18181b | |
--c2-pagination__nav__hover--background-color | color | #f4f4f5 | |
--c2-pagination__nav__hover--border | border | 1px solid transparent | |
--c2-pagination__icon--size | pixel | 16px | |
--c2-pagination__icon--color | color | — | Defaults to the colour of the control it sits in. |
--c2-pagination__ellipsis--color | color | #71717a | |
--c2-pagination__ellipsis--min-width | pixel | 36px | |
--c2-pagination__label--color | color | #71717a | |
--c2-pagination__label--font-size | font-size | 14px | |
--c2-pagination__label--font-weight | font-weight | 500 | |
--c2-pagination__label--gap | pixel | 8px | Space between the rows-per-page label and its select. |
--c2-pagination__page-size-list--min-width | pixel | 56px | Floor for the rows-per-page dropdown: room for a three-digit option, so a one-digit one does not open a sliver. |