Pagination

Pagination lets users navigate between pages of content.

<cw-pagination total-items="120" page-size="10" page="1"></cw-pagination>

import CwPagination from '@cordwainer/cw-elements/dist/react/pagination';

const App = () => <CwPagination totalItems={120} pageSize={10} page={1} />;

Pagination is a controlled component — it doesn’t own or render your data. Listen for cw-change and read the page property to know when to fetch or display a different page.

Examples

Total Items and Page Size

Use the total-items and page-size attributes to determine how many pages are available. The page attribute sets the current page, starting at 1.

<cw-pagination total-items="237" page-size="25" page="1"></cw-pagination>

import CwPagination from '@cordwainer/cw-elements/dist/react/pagination';

const App = () => <CwPagination totalItems={237} pageSize={25} page={1} />;

Listening for Page Changes

When the user clicks a page number or the previous/next buttons, the page property updates and a cw-change event is emitted. Setting page programmatically does not emit cw-change.

<cw-pagination class="pagination-change" total-items="120" page-size="10" page="1"></cw-pagination>
<p>Current page: <span class="pagination-change-output">1</span></p>

<script>
  const pagination = document.querySelector('.pagination-change');
  const output = document.querySelector('.pagination-change-output');

  pagination.addEventListener('cw-change', () => {
    output.textContent = pagination.page;
  });
</script>

Sibling and Boundary Counts

When there are many pages, the page list collapses with an ellipsis. Use sibling-count to control how many pages are shown on either side of the current page, and boundary-count to control how many pages are always shown at the start and end.

<cw-pagination total-items="1000" page-size="10" page="50" sibling-count="2" boundary-count="2"></cw-pagination>

import CwPagination from '@cordwainer/cw-elements/dist/react/pagination';

const App = () => <CwPagination totalItems={1000} pageSize={10} page={50} siblingCount={2} boundaryCount={2} />;

Sizes

Use the size attribute to change the pagination’s size.

<cw-pagination total-items="120" page-size="10" page="2" size="small"></cw-pagination>

<br />

<cw-pagination total-items="120" page-size="10" page="2" size="medium"></cw-pagination>

<br />

<cw-pagination total-items="120" page-size="10" page="2" size="large"></cw-pagination>

import CwPagination from '@cordwainer/cw-elements/dist/react/pagination';

const App = () => (
  <>
    <CwPagination totalItems={120} pageSize={10} page={2} size="small" />

    <br />

    <CwPagination totalItems={120} pageSize={10} page={2} size="medium" />

    <br />

    <CwPagination totalItems={120} pageSize={10} page={2} size="large" />
  </>
);

Disabled

Use the disabled attribute to disable the pagination control.

<cw-pagination total-items="120" page-size="10" page="2" disabled></cw-pagination>

import CwPagination from '@cordwainer/cw-elements/dist/react/pagination';

const App = () => <CwPagination totalItems={120} pageSize={10} page={2} disabled />;

Roadmap

The pagination control currently supports page-number navigation with collapsible ellipses. The following enhancements are planned for future releases:

• Page size selector — an optional control for letting users change page-size themselves.
• Jump to page — an input for typing a page number directly.
• First/last page buttons — optional buttons for jumping straight to the first or last page.

[component-metadata:cw-pagination]

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

<script type="module" src="https://cdn.jsdelivr.net/npm/@cordwainer/cw-elements@1.1.1/cdn/components/pagination/pagination.js"></script>

import 'https://cdn.jsdelivr.net/npm/@cordwainer/cw-elements@1.1.1/cdn/components/pagination/pagination.js';

import '@cordwainer/cw-elements/dist/components/pagination/pagination.js';

import CwPagination from '@cordwainer/cw-elements/dist/react/pagination';

Properties

Learn more about attributes and properties.

Events

Learn more about events.

Parts

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

• <cw-icon>
• <cw-icon-button>