Pagination Control

This control lets you split large amounts of content into pages with navigation buttons and items per page dropdown.

See the Pen jPList Pagination Control by 1rosehip (@1rosehip) on CodePen.

HTML Structure

Pagination control is defined by required data-jplist-control="pagination" data attribute. The data-group attribute defines group of elements that should be paginated. The full list of data attributes can be found here.

<!-- jplist styles - should not be added if bootstrap or other CSS framework is used -->
<link href="jplist.styles.css" rel="stylesheet" type="text/css" />
                
<!-- pagination control -->
<div
        data-jplist-control="pagination"
        data-group="group1"
        data-items-per-page="5"
        data-current-page="0"
        data-name="pagination1">

    <button type="button" data-type="first">«</button>
    <button type="button" data-type="prev">‹</button>

    <div class="jplist-holder" data-type="pages">
        <button type="button" data-type="page">Page {pageNumber}</button>
    </div>

    <button type="button" data-type="next">›</button>
    <button type="button" data-type="last">»</button>
</div>

<!-- content to paginate -->
<div data-jplist-group="group1">

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

</div>

<!-- jplist library -->
<script src="jplist.min.js"></script>
<script>
    jplist.init();
</script>

Add / remove buttons

To show only page buttons just remove the other buttons:

<!-- pagination control -->
<div
        data-jplist-control="pagination"
        data-group="group1"
        data-items-per-page="5"
        data-current-page="0"
        data-name="pagination1">

    <div class="jplist-holder" data-type="pages">
        <button type="button" data-type="page">Page {pageNumber}</button>
    </div>
</div>

The same way it's possible to remove all buttons except previous and next buttons:

<!-- pagination control -->
<div
        data-jplist-control="pagination"
        data-group="group1"
        data-items-per-page="5"
        data-current-page="0"
        data-name="pagination1">

    <button type="button" data-type="prev">‹</button>
    <button type="button" data-type="next">›</button>
</div>

Information Labels

Information labels can be used to print current page number, the whole pages number and other pagination data.

<!-- pagination control -->
<div
        data-jplist-control="pagination"
        data-group="group1"
        data-items-per-page="5"
        data-current-page="0"
        data-name="pagination1">

    ...

    <span data-type="info">
        Page {pageNumber} of {pagesNumber}
    </span>

    <span data-type="info">
        {startItem} - {endItem} of {itemsNumber}
    </span>
</div>

Top and bottom panels

Pagination control can be placed in both top and bottom panels for the better user experience. In this case data-name attribute with the same value should be added. data-items-per-page and data-current-page should also have the same values, but HTML structure including macros can be different:

<!-- pagination control in the top panel -->
<div
        data-jplist-control="pagination"
        data-group="group1"
        data-name="name1"
        data-items-per-page="5"
        data-current-page="0">

    <button type="button" data-type="first">«</button>
    <button type="button" data-type="prev">‹</button>

    <div class="jplist-holder" data-type="pages">
        <button type="button" data-type="page">Page {pageNumber}</button>
    </div>

    <button type="button" data-type="next">›</button>
    <button type="button" data-type="last">»</button>

    <span data-type="info">
        Page {pageNumber} of {pagesNumber}
    </span>
</div>

<!-- content to paginate -->
<div data-jplist-group="group1">

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

</div>

<!-- pagination control in the bottom panel -->
<div
        data-jplist-control="pagination"
        data-group="group1"
        data-name="name1"
        data-items-per-page="5"
        data-current-page="0">

    <button type="button" data-type="first">First Page</button>
    <button type="button" data-type="prev">Previous Page</button>

    <div class="jplist-holder" data-type="pages">
        <button type="button" data-type="page">Page #{pageNumber}</button>
    </div>

    <button type="button" data-type="next">Next Page</button>
    <button type="button" data-type="last">Last Page</button>

    <span data-type="info">
        {startItem} - {endItem} of {itemsNumber}
    </span>
</div>

Items per page select

The number of items per page can be selected by the user using inner select control. The number of items is defined by the option value, where 0 means all items (1 page). data-items-per-page data attribute defines the initial selected option.

<div
        data-jplist-control="pagination"
        data-group="group1"
        data-items-per-page="10"
        data-current-page="0"
        data-name="pagination1">

    <button type="button" data-type="first">«</button>
    <button type="button" data-type="prev">‹</button>

    <div class="jplist-holder" data-type="pages">
        <button type="button" data-type="page">Page {pageNumber}</button>
    </div>

    <button type="button" data-type="next">›</button>
    <button type="button" data-type="last">»</button>

    <!-- items per page select -->
    <select data-type="items-per-page">
        <option value="3"> 3 per page </option>
        <option value="5"> 5 per page </option>
        <option value="10"> 10 per page </option>
        <option value="0"> view all </option>
    </select>
</div>

UL / LI dropdown with custom styles can be used instead of SELECT as items per page selector. The number of items is defined by data-value data attribute, where 0 means all items (1 page). data-items-per-page data attribute defines the initial selected value.

<div
        data-jplist-control="pagination"
        data-group="group1"
        data-items-per-page="5"
        data-current-page="0"
        data-name="pagination1">

    <button type="button" data-type="first">«</button>
    <button type="button" data-type="prev">‹</button>

    <div class="jplist-holder" data-type="pages">
        <button type="button" data-type="page">Page {pageNumber}</button>
    </div>

    <button type="button" data-type="next">›</button>
    <button type="button" data-type="last">»</button>

    <!-- items per page dropdown -->
    <div data-type="items-per-page-dd" class="jplist-dd">
        <div data-type="panel" class="jplist-dd-panel">Items per page</div>

        <div data-type="content" class="jplist-dd-content">
            <div class="jplist-dd-item" data-value="3">3 per page</div>
            <div class="jplist-dd-item" data-value="5">5 per page</div>
            <div class="jplist-dd-item" data-value="10">10 per page</div>
            <div class="jplist-dd-item" data-value="0">View all</div>
        </div>

    </div>
</div>

Bootstrap pagination example

The following example demonstrates how to use jPList pagination with bootstrap controls:

<!-- pagination control -->
<nav
        data-jplist-control="pagination"
        data-group="group1"
        data-items-per-page="3"
        data-current-page="0"
        data-disabled-class="disabled"
        data-selected-class="active"
        data-name="pagination1">

    <!-- first and previous buttons -->
    <ul class="pagination d-inline-flex">
        <li class="page-item" data-type="first"><a class="page-link" href="#">«</a></li>
        <li class="page-item" data-type="prev"><a class="page-link" href="#">‹</a></li>
    </ul>

    <!-- pages buttons -->
    <ul class="pagination d-inline-flex" data-type="pages">
        <li class="page-item" data-type="page"><a class="page-link" href="#">{pageNumber}</a></li>
    </ul>

    <!-- next and last buttons -->
    <ul class="pagination d-inline-flex">
        <li class="page-item" data-type="next"><a class="page-link" href="#">›</a></li>
        <li class="page-item" data-type="last"><a class="page-link" href="#">»</a></li>
    </ul>

    <!-- items per page dropdown -->
    <div class="dropdown d-inline-flex ml-3"
         data-type="items-per-page-dd"
         data-opened-class="show">

        <button
                data-type="panel"
                class="btn btn-primary dropdown-toggle"
                type="button">
            Dropdown button
        </button>

        <div
            data-type="content"
            class="dropdown-menu"
            aria-labelledby="dropdownMenuButton">

            <a class="dropdown-item" href="#" data-value="3">3 per page</a>
            <a class="dropdown-item" href="#" data-value="6">6 per page</a>
            <a class="dropdown-item" href="#" data-value="9">9 per page</a>
            <a class="dropdown-item" href="#" data-value="0">View All</a>

        </div>
    </div>

    <!-- information labels -->
    <span data-type="info" class="badge badge-secondary ml-3 p-2">
        Page {pageNumber} of {pagesNumber}
    </span>

</nav>

Jump to top

data-jump data attribute can be used to scroll page to the specified location when user clicks a page button. data-jump="top" scrolls page to the top. Any CSS selector can be used instead of top keyword.

<!-- pagination control -->
<div
        data-jplist-control="pagination"
        data-group="group1"
        data-items-per-page="5"
        data-current-page="0"
        data-jump="top"
        data-name="pagination1">

    ...
</div>

<!-- content to paginate -->
<div data-jplist-group="group1">

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

</div>

Pagination Classes

Pagination control has dynamically updated classes jplist-pages-number-... and jplist-items-number-.... For example it has jplist-pages-number-0 and jplist-items-number-0 classes after search that returns no results. This behaviour can be used to apply special styles to the inner pagination elements in different cases.

Also pagination control can accept different styles via data attributes. More details can be found here.

Deep Linking

Deep links can be used to keep user selections and control states after the page refresh. To implement them data-id attribute should be added to HTML structure and deepLinking setting should be true in jPList parameters.

In the example below deep link may look like http://www.example.com/page#group=group1&paging1=0-5 where group1 is taken from data-jplist-group="group1", 0 is current selected page and 5 is the current number of items per page.

<!-- pagination control -->
<div
        data-jplist-control="pagination"
        data-group="group1"
        data-items-per-page="5"
        data-current-page="0"
        data-id="paging1"
        data-name="paging1">

    ...
</div>

<!-- content to paginate -->
<div data-jplist-group="group1">

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

</div>
                
<script src="jplist.min.js"></script>
<script>
    jplist.init({
        deepLinking: true
    });
</script>

Storage

Local storage, session storage or cookies can be used to keep user selections and control states after the page refresh. To implement them data-id attribute should be added to HTML structure and storage setting should be passed to jPList constructor.

<!-- pagination control -->
<div
        data-jplist-control="pagination"
        data-group="group1"
        data-items-per-page="5"
        data-current-page="0"
        data-id="paging1"
        data-name="paging1">

    ...
</div>

<!-- content to paginate -->
<div data-jplist-group="group1">

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

    <!-- item -->
    <div data-jplist-item>
        ...
    </div>

</div>

<script src="jplist.min.js"></script>
<script>
    jplist.init({
        storage: 'localStorage', //'localStorage', 'sessionStorage' or 'cookies'
        storageName: 'my-page-storage' //the same storage name can be used to share storage between multiple pages
    });
</script>

Data Attributes

The full list of pagination data attributes.

Name	Description	Values
`data-jplist-control`	Defines pagination control.	"pagination"
`data-group`	Defines group of items that should be paginated. For example, if pagination control has data-group="group1" then items group should have data-jplist-group="group1" data attribute.	any text value
`data-name`	The data-name attribute is used to identify the same controls in different panels. Different controls should have different data-name attributes. By default, data-name attribute has default value.	any text value
`data-items-per-page`	Defines number of items per page.	numeric value
`data-current-page`	Defines initial page number starting from 0.	numeric value
`data-range`	Defines the maximal number of visible pagination button.	numeric value
`data-selected-class`	Optional data attribute that defines CSS class of selected / active page button.	CSS class name, by default jplist-selected
`data-disabled-class`	Optional data attribute that defines CSS class of disabled buttons and can be applied on first, previous, next, and last buttons.	CSS class name, by default jplist-disabled
`data-opened-class`	Optional data attribute that defines CSS class of opened items per page dropdown with custom styles.	CSS class name, by default jplist-dd-opened
`data-jump`	This data attribute can be used to scroll page to the specified location when user clicks a page button. data-jump="top" scrolls page to the top. Any CSS selector can be used instead of top keyword.	top keyword or any CSS selector
`data-id`	This attribute is used for deep linking.	any text value that may contain letters, digits, underscores or dashes

Inner elements

Data attributes of inner elements.

Name	Description	Values
`data-type="first"`	Defines a button. Once clicked, the first page will be opened.	"first"
`data-type="last"`	Defines a button. Once clicked, the last page will be opened.	"last"
`data-type="prev"`	Defines a button. Once clicked, the previous page will be opened.	"prev"
`data-type="next"`	Defines a button. Once clicked, the next page will be opened.	"next"
`data-type="page"`	Defines HTML of page button. Once clicked, the specified page number will be opened.	"next"
`data-type="info"`	Defines information label.	"info"
`data-type="items-per-page"`	Items per page select control.	"items-per-page"
`data-type="items-per-page-dd"`	Items per page UL / LI dropdown with custom styles.	"items-per-page-dd"

Macros

The macros represent pagination data and can be used in information labels and other places.

Name	Description
`{pageNumber}`	Indicates the current page number. Can be used in page button and in information labels.
`{pagesNumber}`	Indicates the whole pages number. Can be used in information labels.
`{startItem}`	Indicates starting content item.
`{endItem}`	Indicates ending content item.
`{itemsNumber}`	Indicates the number of content items.