Pagination

Pagination is a group of segmented buttons that control the offset of a list of items. Users select which “page” of items to view, typically for a table.

Basics

Create a pagination button group with an element that has class .hc-pagination. Inside, include as many <button> elements with class .hc-pagination-item as needed to display the relevant pages and navigation controls specific to your table or view.

The active page’s button should have the additional class .hc-is--active.

HTML

Expand Edit in Playground Copy


<div class="hc-pagination" role="navigation" aria-label="Paginated navigation">
  <button class="hc-pagination-item" aria-label="Previous page">
    <i class="hc-icon hc-icon--chevron-left hc-icon--16"></i>
  </button>
  <button class="hc-pagination-item">1</button>
  <button class="hc-pagination-item">2</button>
  <button class="hc-pagination-item hc-is--active" aria-current="true">3</button>
  <button class="hc-pagination-item">4</button>
  <button class="hc-pagination-item">5</button>
  <button class="hc-pagination-item">...</button>
  <button class="hc-pagination-item">100</button>
  <button class="hc-pagination-item" aria-label="Next page">
    <i class="hc-icon hc-icon--chevron-right hc-icon--16"></i>
  </button>
</div>

Note that all hover states, borders, and rounded corners are handled automatically. The only thing you need to do is make sure each button is a sibling inside of the wrapper element.

Accessibility note

Please include role="navigation' and an appropriate aria-label on the .hc-pagination wrapper element describing what it is.

Please also ensure that the appropriate aria-label is present on the Previous and Next buttons, as these buttons do not naturally contain any text, and that aria-current="true" is set to the active button.

General guidelines

Generally you should set Previous and Next as the first and last buttons of the pagination group, allowing the user to progress backward or forward one page, respectively.

When there are 5 or fewer total pages: include all numbered pages as buttons in the middle, with the current page placed in the center as long as possible. If size is an issue, you can make this number 3 instead.

If there are more than 5 pages: it’s best to start with numbered pages 1-5 followed by an ellipsis button that jumps a certain number of pages forward. Again, if size is an issue, you can omit the ellipsis.

Notes on using the ellipsis button

The number of pages progressed by the ellipsis button will depend on the total number of pages the user can view, but should generally be an offset equal to the number of pages displayed as buttons. For instance, if you show 5 numbered buttons, the offset should be 5. In extreme cases where you show 10 numbered buttons, the offset would be 10.

An ellipsis/offset button can also appear at the start of the group if the user is deep into results. You can have both a start and end ellipsis in large result sets where the user is in the middle.

If the user is early in the list and there is a right ellipsis, include 1 button for the final page’s number that takes the user there and then end with the Next button.
If the user is late in the list and there is a left ellipsis, include 1 button for the first page’s number that takes the user to the beginning, right after the Previous button.
If the user is in the middle of a large list, you can show, in order: Previous, first page, ellipsis, 5 numbered buttons, ellipsis, last page, Next.

Showing the count

For large result sets it’s ideal to show the user the total number of results as well as their placement within those results. Wrap the .hc-pagination inside of an element with class .hc-pagination-group and place the count inside of a sibling .hc-pagination-count element.

This count should go directly below pagination group, centered with it. If your table also needs to allow the user to change the number of rows per page, this count may need to relocate (see below).

30-39 of 1,000

HTML

Expand Edit in Playground Copy


<div class="hc-pagination-group">
  <div class="hc-pagination" role="navigation" aria-label="Paginated navigation">
    <button class="hc-pagination-item" aria-label="Previous page">
      <i class="hc-icon hc-icon--chevron-left hc-icon--16"></i>
    </button>
    <button class="hc-pagination-item">1</button>
    <button class="hc-pagination-item">2</button>
    <button class="hc-pagination-item hc-is--active" aria-current="true">3</button>
    <button class="hc-pagination-item">4</button>
    <button class="hc-pagination-item">5</button>
    <button class="hc-pagination-item">...</button>
    <button class="hc-pagination-item">100</button>
    <button class="hc-pagination-item" aria-label="Next page">
      <i class="hc-icon hc-icon--chevron-right hc-icon--16"></i>
    </button>
  </div>
  <div class="hc-pagination-count">
    30-39 of 1,000
  </div>
</div>

Count, items per page, and pagination

If your table or other component requires showing all 3 pagination-related elements (the current page’s count, a control for to manage the number of items per page, and the pagination group itself), then these should all sit in a row together.

Use the same wrapping element with class .hc-pagination-group but ensure that this element is inside of some parent element with class .hc-app-content to handle the orientation on various screen sizes. If you’re using the Layout framework here this is taken care of already, but if not there needs to be some parent element with this class for the container queries to work.

30-39 of 1,000

Items per page:

HTML

Expand Edit in Playground Copy


<div class="hc-pagination-group">
  <div class="hc-pagination-count">
    30-39 of 1,000
  </div>
  <div class="hc-pagination" role="navigation" aria-label="Paginated navigation">
    <button class="hc-pagination-item" aria-label="Previous page">
      <i class="hc-icon hc-icon--chevron-left hc-icon--16"></i>
    </button>
    <button class="hc-pagination-item">1</button>
    <button class="hc-pagination-item">2</button>
    <button class="hc-pagination-item hc-is--active" aria-current="true">3</button>
    <button class="hc-pagination-item">...</button>
    <button class="hc-pagination-item">100</button>
    <button class="hc-pagination-item" aria-label="Next page">
      <i class="hc-icon hc-icon--chevron-right hc-icon--16"></i>
    </button>
  </div>
  <div class="hc-pagination-control">
    <label for="pagination-select">Items per page:</label>
    <select class="hc-select hc-select--sm" id="pagination-select">
      <option>10</option>
      <option>25</option>
      <option>50</option>
    </select>
  </div>
</div>

On large screens with a content section sufficiently big enough (as reported by .hc-app-content), the pagination group element uses grid-template-columns of 1fr auto 1fr to ensure the first and last columns are sized the same, and that therefore the pagination is always centered correctly.

Additional examples

The available space present for the pagination group will dictate to an extent how many numbered buttons you can display, and whether you can use the ellipsis buttons as well.

Use the following examples as guidelines on when and how to show the various pagination button options.

User is on page 9 of a 22 page result set:

Same as above but size constraints are present:

User is on page 19 of a 22 page result set:

(no end ellipsis since remainder < 5)

User is on the last page of a 3-page result set:

(no Next button since we're on the last page)

HTML

Expand Edit in Playground Copy


<p>User is on page 9 of a 22 page result set:</p>
<div class="hc-pagination" role="navigation" aria-label="Paginated navigation">
  <button class="hc-pagination-item" aria-label="Previous page">
    <i class="hc-icon hc-icon--chevron-left hc-icon--16"></i>
  </button>
  <button class="hc-pagination-item">1</button>
  <button class="hc-pagination-item">...</button>
  <button class="hc-pagination-item">7</button>
  <button class="hc-pagination-item">8</button>
  <button class="hc-pagination-item hc-is--active">9</button>
  <button class="hc-pagination-item">10</button>
  <button class="hc-pagination-item">11</button>
  <button class="hc-pagination-item">...</button>
  <button class="hc-pagination-item">22</button>
  <button class="hc-pagination-item" aria-label="Next page">
    <i class="hc-icon hc-icon--chevron-right hc-icon--16"></i>
  </button>
</div>
<p class="mt-6">Same as above but size constraints are present:</p>
<div class="hc-pagination" role="navigation" aria-label="Paginated navigation">
  <button class="hc-pagination-item" aria-label="Previous page">
    <i class="hc-icon hc-icon--chevron-left hc-icon--16"></i>
  </button>
  <button class="hc-pagination-item">8</button>
  <button class="hc-pagination-item hc-is--active">9</button>
  <button class="hc-pagination-item">10</button>
  <button class="hc-pagination-item" aria-label="Next page">
    <i class="hc-icon hc-icon--chevron-right hc-icon--16"></i>
  </button>
</div>
<p class="mt-6">User is on page 19 of a 22 page result set:</p>
<p class="text-base -mt-2 mb-1">(no end ellipsis since remainder < 5)</p>
<div class="hc-pagination" role="navigation" aria-label="Paginated navigation">
  <button class="hc-pagination-item" aria-label="Previous page">
    <i class="hc-icon hc-icon--chevron-left hc-icon--16"></i>
  </button>
  <button class="hc-pagination-item">1</button>
  <button class="hc-pagination-item">...</button>
  <button class="hc-pagination-item">18</button>
  <button class="hc-pagination-item hc-is--active">19</button>
  <button class="hc-pagination-item">20</button>
  <button class="hc-pagination-item">21</button>
  <button class="hc-pagination-item">22</button>
  <button class="hc-pagination-item" aria-label="Next page">
    <i class="hc-icon hc-icon--chevron-right hc-icon--16"></i>
  </button>
</div>
<p class="mt-6">User is on the last page of a 3-page result set:</p>
<p class="text-base -mt-2 mb-1">(no Next button since we're on the last page)</p>
<div class="hc-pagination" role="navigation" aria-label="Paginated navigation">
  <button class="hc-pagination-item" aria-label="Previous page">
    <i class="hc-icon hc-icon--chevron-left hc-icon--16"></i>
  </button>
  <button class="hc-pagination-item">1</button>
  <button class="hc-pagination-item">2</button>
  <button class="hc-pagination-item hc-is--active">3</button>
</div>