Pagination

<quiet-pagination>

stable

since 1.0

Pagination splits content into numbered pages so users can navigate datasets in manageable chunks.

<quiet-pagination total-pages="5"></quiet-pagination>

Examples Jump to heading

Setting the number of pages Jump to heading

Use the total-pages attribute to set the total number of pages available.

<quiet-pagination total-pages="20"></quiet-pagination>

Setting the initial page Jump to heading

Use the page attribute to set the initial page that's selected.

<quiet-pagination total-pages="5" page="3"></quiet-pagination>

Responding to page changes Jump to heading

When the user changes the page, the quiet-page-change event will be emitted. You can listen to this event to update the view or redirect the user to the appropriate destination.

<quiet-pagination 
  total-pages="10" 
  page="1" 
  id="pagination__responding"
></quiet-pagination>

<script>
  const pagination = document.getElementById('pagination__responding');

  pagination.addEventListener('quiet-page-change', () => {
    //
    // Update the view here
    //
    console.log(`Showing page ${pagination.page}`);

    //
    // Alternatively, you can send the user to a URL:
    //
    // location.href = `/page/${pagination.page}`
    //
  });
</script>

Changing the page programmatically Jump to heading

Set the page property to any valid page to change the current page. Note that programmatic changes will not dispatch page change events.

<quiet-pagination 
  total-pages="10" 
  page="1"
  id="pagination__setting"
></quiet-pagination>

<quiet-select label="Page" value="1" style="max-width: 100px; margin-block-start: 1.5rem;">
  <option value="1">1</option>
  <option value="2">2</option>
  <option value="3">3</option>
  <option value="4">4</option>
  <option value="5">5</option>
  <option value="6">6</option>
  <option value="7">7</option>
  <option value="8">8</option>
  <option value="9">9</option>
  <option value="10">10</option>
</quiet-select>

<script>
  const pagination = document.getElementById('pagination__setting');
  const select = pagination.nextElementSibling;

  select.addEventListener('input', () => {
    pagination.page = select.value;
  });

  pagination.addEventListener('quiet-page-change', () => {
    select.value = pagination.page;
  });
</script>

Changing the format Jump to heading

Set the format attribute to compact or standard to change the pagination's format.

              
                Compact
                Standard

<quiet-pagination 
  format="compact"
  total-pages="5"
  siblings="3"
  id="pagination__format"
></quiet-pagination>

<quiet-radio label="Format" value="compact" class="quiet-vh-label" style="margin-block-start: 1.5rem;">
  <quiet-radio-item value="compact">Compact</quiet-radio-item>
  <quiet-radio-item value="standard">Standard</quiet-radio-item>
</quiet-select>

<script>
  const pagination = document.getElementById('pagination__format');
  const radio = pagination.nextElementSibling;

  radio.addEventListener('input', () => {
    pagination.format = radio.value;
  });  
</script>

Changing the appearance Jump to heading

Set the appearance attribute to normal, filled, or unstyled to change the pagination's appearance.

<quiet-pagination appearance="normal" total-pages="5"></quiet-pagination>
<quiet-pagination appearance="filled" total-pages="5"></quiet-pagination>
<quiet-pagination appearance="unstyled" total-pages="5"></quiet-pagination>

Changing the number of buttons Jump to heading

Use the siblings attribute to control the number of pages that show on each side of the current page. The default is 3. The minimum is 2.

<quiet-pagination siblings="2" total-pages="20" page="10"></quiet-pagination>
<quiet-pagination siblings="3" total-pages="20" page="10"></quiet-pagination>
<quiet-pagination siblings="4" total-pages="20" page="10"></quiet-pagination>

Changing the size Jump to heading

Pagination controls are sized relative to the current font size. To change their size, apply font-size to the pagination or an ancestor element.

<quiet-pagination 
  total-pages="5"
  page="1"
  style="font-size: 0.75rem;"
></quiet-pagination>

<quiet-pagination 
  total-pages="5"
  page="1"
  style="font-size: 1rem;"
></quiet-pagination>

<quiet-pagination 
  total-pages="5"
  page="1"
  style="font-size: 1.25rem;"
></quiet-pagination>

Using custom icons Jump to heading

Use the previous-icon, next-icon, and jump-icon slots to override the default icons.

<quiet-pagination total-pages="10">
  <quiet-icon slot="previous-icon" name="arrow-left"></quiet-icon>
  <quiet-icon slot="next-icon" name="arrow-right"></quiet-icon>
  <quiet-icon slot="jump-backward-icon" name="chevrons-left"></quiet-icon>
  <quiet-icon slot="jump-forward-icon" name="chevrons-right"></quiet-icon>
</quiet-pagination>

Removing nav buttons Jump to heading

Use without-nav to remove the previous and next navigation buttons.

<quiet-pagination 
  total-pages="10"
  page="1"
  without-nav
></quiet-pagination>

Disabling Jump to heading

Add the disabled attribute to disable the pagination control.

<quiet-pagination 
  total-pages="10"
  page="1"
  disabled
></quiet-pagination>

Styling pagination Jump to heading

Pagination controls come with a simple, minimal appearance. Feel free to customize them with your own styles.

<quiet-pagination total-pages="10" page="5" appearance="unstyled" id="pagination__styling"></quiet-pagination>

<style>
  #pagination__styling {
    &::part(button) {
      border-radius: 9999px;
    }

    /* Light gray circles for previous and next buttons */
    &::part(button-previous),
    &::part(button-next) {
      background-color: var(--quiet-neutral-fill-softer);
    }

    /* The current page is larger and has a subtle gradient */
    &::part(button-current) {
      background: linear-gradient(45deg, #ff1493, #ff69b4);
      color: white;
      scale: 1.1;
    }
  }
</style>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-pagination> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet-browser@1.0.0/dist/components/pagination/pagination.js';

To manually import <quiet-pagination> from npm, use the following code.

import '@quietui/quiet/dist/components/pagination/pagination.js';

Slots Jump to heading

Pagination supports the following slots. Learn more about using slots

Name	Description
`previous-icon`	A custom icon to use for the previous button.
`next-icon`	A custom icon to use for the next button.
`jump-backward-icon`	A custom icon to use for the jump backward button.
`jump-forward-icon`	A custom icon to use for jump forward button.

Pagination has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`label`	A label to use to describe the control to assistive devices. Defaults to "Pagination" when not set.	`string`	`''`
`totalPages` `total-pages`	The total number of pages to show.	`number`	`1`
`page`	The current page.	`number`	`1`
`siblings`	The number of pages to show on each side of the current page. Minimum 2.	`number`	`3`
`jump`	The number of pages to increase or decrease when jump buttons are clicked.	`number`	`5`
`format`	How the pagination will display buttons.	`'compact' 'standard'`	`'standard'`
`disabled`	Disables the pagination control.	`boolean`	`false`
`appearance`	Determine's the pagination's appearance.	`'normal' 'filled' 'unstyled'`	`'normal'`
`withoutNav` `without-nav`	Removes the previous and next buttons.	`boolean`	`false`

Events Jump to heading

Pagination dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`quiet-before-page-change`	Emitted when the page is going to change but before it actually changes. Calling `event.preventDefault()` will prevent the page from changing. Inspect `event.detail` to get the `currentPage` and `requestedPage` properties.
`quiet-page-change`	Emitted after the page has been changed and the UI has been updated.

CSS parts Jump to heading

Pagination exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`nav`	The navigation container, a `<nav>` element.	`::part(nav)`
`list`	The list that contains the pagination items, a `<ul>` element.	`::part(list)`
`item`	A pagination item, an `<li>` element.	`::part(item)`
`button`	A pagination button, a `<button>` element.	`::part(button)`
`button-first`	The button that navigates to the first page.	`::part(button-first)`
`button-previous`	The button that navigates to the previous page.	`::part(button-previous)`
`button-next`	The button that navigates to the next page.	`::part(button-next)`
`button-last`	The button that navigates to the last page.	`::part(button-last)`
`button-page`	A button that navigates to a specific page.	`::part(button-page)`
`button-current`	The button that represents the current page.	`::part(button-current)`
`button-jump-backward`	The jump backward button.	`::part(button-jump-backward)`
`button-jump-forward`	The jump forward button.	`::part(button-jump-forward)`
`range`	The page range that shows the page when viewed in the compact format, e.g. "1 of 10".	`::part(range)`

Custom States Jump to heading

Pagination has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`disabled`	Applied when the pagination is disabled.	`:state(disabled)`

Dependencies Jump to heading

Pagination automatically imports the following elements. Sub-dependencies are also included in this list.

<quiet-icon>

Pagination

Examples Jump to heading #

Setting the number of pages Jump to heading #

Setting the initial page Jump to heading #

Responding to page changes Jump to heading #

Changing the page programmatically Jump to heading #

Changing the format Jump to heading #

Changing the appearance Jump to heading #

Changing the number of buttons Jump to heading #

Changing the size Jump to heading #

Using custom icons Jump to heading #

Removing nav buttons Jump to heading #

Disabling Jump to heading #

Styling pagination Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Events Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #

Dependencies Jump to heading #