Version 6.3 Released!

Click to checkout the new features

Pagination

Overview

If you would prefer to display your data as pages rather than a scrolling list Tabulator can help you out there too.

Loading Example...
Source Code

HTML

<div id="example-table"></div>

JavaScript

//Build Tabulator
var table = new Tabulator("#example-table", {
    layout:"fitColumns",
    pagination:"local",
    paginationSize:6,
    paginationSizeSelector:[3, 6, 8, 10],
    movableColumns:true,
    paginationCounter:"rows",
    columns:[
        {title:"Name", field:"name", width:200},
        {title:"Progress", field:"progress", formatter:"progress", sorter:"number"},
        {title:"Gender", field:"gender"},
        {title:"Rating", field:"rating", formatter:"star", hozAlign:"center", width:100},
        {title:"Favourite Color", field:"col"},
        {title:"Date Of Birth", field:"dob", hozAlign:"center", sorter:"date"},
        {title:"Driver", field:"car", hozAlign:"center", formatter:"tickCross"},
    ],
});

There are two forms of pagination available. local pagination, where Tabulator will parse in all available data and then paginate this data set. Or remote pagination, where Tabulator will load individual pages of data via Ajax from a remote server.

When pagination is enabled, a footer element will be added to the bottom of the table, with a range of navigation controls to allow your users to easily switch between pages.

The first page of a table will automatically be loaded when the table is created if pagination is enabled.

If you are a Laravel user then you should find that the auto generated URL's and data processing work straight out the box with no additional configuration needed.

Note: Changing the filter, sorting or toggling a groups visibility, while pagination is enabled will revert the table back to the first page.

Remote Pagination

To enable remote pagination, set the pagination option to true, the paginationMode option to remote, and set the url for the Ajax request using the ajaxURL parameter. You can also pass an optional object to ajaxParams for any parameters you want to pass with the url (these should be static parameters, the page number etc, will be added later on).

By default the page size will be set by the amount of data returned by the remote server, if you need to tell the remote server how many rows to send you can set the paginationSize parameter.

var table = new Tabulator("#example-table", {
    pagination:true, //enable pagination
    paginationMode:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    ajaxParams:{token:"ABC123"}, //set any standard parameters to pass with the request
    paginationSize:5, //optional parameter to request a certain number of rows per page
    paginationInitialPage:2, //optional parameter to set the initial page to load
});

Request URL

Tabulator will automatically create a page request URL when a user selects a page.

By default a url will be generated using the provided ajaxURL and a number of system generated parameters:

  • page - the page number being requested
  • size - the number of rows to a page (if paginationSize is set)
  • sorters - the first current sorters(if any)
  • filter - an array of the current filters (if any)

If you need to change the names of any of these parameters to fit your existing system, you can use the dataSendParams option to set alternative parameter names.

var table = new Tabulator("#example-table", {
    pagination:true, //enable pagination
    paginationMode:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    dataSendParams:{
        "page":"pageNo", //change page request parameter to "pageNo"
    } ,
});

Custom Pagination URL Construction

If you need to have more complex control over the request URL, you can pass a callback to the ajaxURLGenerator option to return the URL you wish to use for each page, the pagination information such as page number and page size can be found in the prams argument

var table = new Tabulator("#example-table", {
    ajaxURLGenerator:function(url, config, params){
        //url - the url from the ajaxURL property or setData function
        //config - the request config object from the ajaxConfig property
        //params - the params object from the ajaxParams property, this will also include any pagination, filter and sorting properties based on table setup

        //return request url
        return url + "?params=" + encodeURI(JSON.stringify(params)); //encode parameters as a json object
    },
});

Note: If you use a paginator function you will need to manually add the sort and filter parameters to the request url if required.

Returned Response Data

The remote server should return a JSON formatted object with the following structure:

{
    "last_page":15, //the total number of available pages (this value must be greater than 0)
    "data":[ // an array of row data objects
        {id:1, name:"bob", age:"23"}, //example row data object
    ]
}

If you need to change the names of any of these parameters to fit your existing system, you can use the dataReceiveParams option to set alternative parameter names.

var table = new Tabulator("#example-table", {
    pagination:true, //enable pagination
    paginationMode:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    dataReceiveParams:{
        "last_page":"max_pages", //change last_page parameter name to "max_pages"
    } ,
});

Local Pagination

Local pagination works by loading the entire data set into the table then generating paged views of that data.

The pagination module is set to use local pagination by default, so to enable local mode pagination, simple enable table pagination by seeting the pagination option to true,.

var table = new Tabulator("#example-table", {
    pagination:true, //enable pagination.
});

Setting Page size

With local pagination there are a couple ways to set the number of rows in each page.

You can specify the page size during table creation by setting the paginationSize option. If no height option is specified the table will resize to fit the number of rows on the page.

var table = new Tabulator("#example-table", {
    pagination:true, //enable.
    paginationSize:5, // this option can take any positive integer value
});

Alternatively, if you specify the height of the table, either in CSS or by using the height option, and don't define the paginationSize option the page size will be automatically set to fill the height of the table.

var table = new Tabulator("#example-table", {
    height:"300px",
    pagination:true, //enable.
});

Note: If you set the height of the table and use the paginationSize option, the number of rows may either not fill the available space, or not fit in the table and a vertical scrollbar will appear.

Setting Initial Page

By default Tabulator will load the first page of data when the table is initially loaded. You can use the paginationInitialPage option to specify that a specific page should be loaded when the table first loads.

var table = new Tabulator("#example-table", {
    pagination:true, //enable pagination.
    paginationInitialPage:2, // this option can take any positive integer value (default = 1)
});

Pagination Control Element

Custom Pagination Control Element

By default the pagination controls are added to the footer of the table. If you wish the controls to be created in another element pass a DOM node or a CSS selector for that element to the paginationElement option.

var table = new Tabulator("#example-table", {
    pagination:true,
    paginationElement:paginationElement, //build pagination controls in this element
});

Set Number of Pagination Buttons

The number of pagination page buttons shown in the footer using the paginationButtonCount option. By default this has a value of 5.

var table = new Tabulator("#example-table", {
    paginationButtonCount:3, //use 3 page buttons in the footer
});

Show Page Size Select Element

If you would like the user to be able to set the number of rows on each page, you can use the paginationSizeSelector option, which will add a page size selection select element to the table footer.

Auto Generate Page Size List

Setting this option to true will cause Tabulator to create a list of page size options, that are multiples of the current page size. In the example below, the list will have the values of 5, 10, 15 and 20.

When using the page size selector like this, if you use the setPageSize function to set the page size to a value not in the list, the list will be regenerated using the new page size as the starting value

var table = new Tabulator("#example-table", {
    pagination:true,
    paginationSize:5,
    paginationSizeSelector:true, //enable page size select element and generate list options
});

Sepecifying the Page Size List

If you want to specific the available page sizes you can pass an array of integers to the paginationSizeSelector option.

var table = new Tabulator("#example-table", {
    pagination:true,
    paginationSize:10,
    paginationSizeSelector:[10, 25, 50, 100], //enable page size select element with these options
});

When using the page size selector like this, if you use the setPageSize function to set the page size to a value not in the list, it will be added to the top of the list

You can also pass a boolean value of true into the array, this will show an "All" option that will show all available rows on one page

var table = new Tabulator("#example-table", {
    pagination:true,
    paginationSize:10,
    paginationSizeSelector:[10, 25, 50, 100, true], //select list with an "all" option at the end of the list
});

Page Size Label

When the page size selector is enabled it is diplayed to the right of a text label to make its purpose clear. If you want to change the text in this label it can be updated through the localization module

Add Row Behaviour

When using the addRow function on a paginated table, rows will be added relative to the current page (ie to the top or bottom of the current page), with overflowing rows being shifted onto the next page.

If you would prefer rows to be added relative to the table (firs/last page) then you can use the paginationAddRow option. it can take one of two values:

  • page - add rows relative to current page (default)
  • table - add rows relative to the table
var table = new Tabulator("#example-table", {
    pagination:true,
    paginationAddRow:"table", //add rows relative to the table
});

Pagination Counter

You can choose to display a pagination counter in the bottom left of the footer that shows a summary of the current number of rows shown out of the total.

To enable this you need to set the paginationCounter option in the table constructor.

var table = new Tabulator("#example-table", {
    pagination:true,
    paginationCounter:"rows", //add pagination row counter
});

Built In Counters

Tabulator comes with a couple of built in counters that format the page counter differently for different needs

Note: For a guide to adding your own counters to this list, have a look at the Extending Tabulator section.

Rows Counter

The rows counter can be selected by passing the value "rows" to the paginationCounter option

var table = new Tabulator("#example-table", {
    pagination:true,
    paginationCounter:"rows", //add pagination row counter
});

This will then display a summary of the currently displayed rows in the format "Showing X-X of X rows"

Pages Counter

The pages counter can be selected by passing the value "pages" to the paginationCounter option

var table = new Tabulator("#example-table", {
    pagination:true,
    paginationCounter:"pages", //add pagination page counter
});

This will then display a summary of the currently displayed pages in the format "Showing X of X pages"

Custom Counters

If you want to have a fully customized counter, then you can pass a function to the paginationCounter option

The formatter function accepts 5 arguments:

  • pageSize - Number of rows shown per page
  • currentRow - First visible row position
  • currentPage - Current page
  • totalRows - Total rows in table
  • totalPages - Total pages in table

The function must return the contents of the counter, either the text value of the counter, valid HTML or a DOM node

var table = new Tabulator("#example-table", {
    pagination:true,
    paginationCounter:function(pageSize, currentRow, currentPage, totalRows, totalPages){
        return "Showing " pageSize +  " rows of " + totalRows + " total";
    }
});

Counter Element

By default the counter will be displayed in the left of the table footer. If you would like it displayed in another element pass a DOM node or a CSS selector for that element to the paginationCounterElement option.

var table = new Tabulator("#example-table", {
    pagination:true,
    paginationCounter:"rows",
    paginationCounterElement:"#page-count", // show counter in this element instead of footer
});

Ajax Total Row Counting

When working with remote ajax pagination the table does not know how exactly how many total rows are available, because it only loads one page of row data at a time.

If you are using remote pagination with a counter then you need to include the last_row value in your response data that is set to the total number of rows available

{
    "last_page":15, //the total number of available pages (this value must be greater than 0)
    "last_row":246, //the total number of rows pages (this value must be greater than 0)
    "data":[ // an array of row data objects
        {id:1, name:"bob", age:"23"}, //example row data object
    ]
}

If your remote response is missing the last_row value then Tabulator will attempt to estimate the number of rows by multiplying the page size by the last_page value

Localization of Counters

You can customise the text of the built in counters using the counters pagination property in the lang module

var table = new Tabulator("#example-table", {
    locale:true,
    langs:{
        "default":{
            "pagination":{
                "counter":{
                    "showing": "Showing",
                    "of": "of",
                    "rows": "rows",
                    "pages": "pages",
                }
            },
        }
    },
});

For full details on how to adjust localization, please read the localization module docs

Managing Pagination

A number of additional controls are available to help customize the pagination experience.

Set Current Page

When pagination is enabled the table footer will contain a number of pagination controls for navigating through the data.

In addition to these controls it is possible to change page using the setPage function

table.setPage(5); // show page 5

The setPage function takes one parameter, which should be an integer representing the page you wish to see. There are also four strings that you can pass into the parameter for special functions.

  • "first" - show the first page
  • "prev" - show the previous page
  • "next" - show the next page
  • "last" - show the last page

The setPage method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.setPage(1)
.then(function(){
    //run code after table has been successfully updated
})
.catch(function(error){
    //handle error loading data
});

Load Next Page

You can change to show the next page using the nextPage function.

table.nextPage(); // load the next page

The nextPage method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.nextPage()
.then(function(){
    //run code after table has been successfully updated
})
.catch(function(error){
    //handle error loading data
});

Load Previous Page

You can change to show the next page using the previousPage function.

table.previousPage(); // load the previous page

The previousPage method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.previousPage()
.then(function(){
    //run code after table has been successfully updated
})
.catch(function(error){
    //handle error loading data
});

Load Page For a Specific Row

You can load the page for a specific row using the setPageToRow function and passing in any of the standard row component look up options for the row you want to scroll to.

table.setPageToRow(12); // load the previous page

The setPageToRow method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.setPageToRow(12)
.then(function(){
    //run code after table has been successfully updated
})
.catch(function(error){
    //handle error loading data
});

If you have a Row Component for a specific row, you can call the pageTo function on the component to load the page for that row.

row.pageTo(); //load page that contains row

Local Pagination Only
This functionality is only available on local pagination. when using remote pagination Tabulator has ow way to lookup which page the requested row is on.

Change Page Size

You can change the page size at any point by using the setPageSize function. (this setting will be ignored if using remote pagination with the page size set by the server)

table.setPageSize(50); // show 50 rows per page

Get Page Size

To retrieve the number of rows allowed per page you can call the getPageSize function:

var pageSize = table.getPageSize(); // returns number of rows allowed per page

Get Current Page Number

To retrieve the current page use the getPage function. this will return the number of the current page. If pagination is disabled this will return false.

table.getPage(); // returns current page

Get Maximum Page Number

To retrieve the maximum available page use the getPageMax function. this will return the number of the maximum available page. If pagination is disabled this will return false.

table.getPageMax(); // returns maximum page

Page Out of Range Behaviour

When loading paginated data, if the current page shown is larger thant the max page, Tabulator will just continue to show the data presented to it, to minimize the disruption to the user.

If you would prefer to force the behaviour in this instance, you can use the "paginationOutOfRange" option.

var table = new Tabulator("#example-table", {
    pagination:true, //enable pagination
    paginationOutOfRange:"last", //show the last page if pagination is out of range
});

The paginationOutOfRange option takes any of the standard setPage values, this can either be an integer representing the page or there are also four strings that you can pass into the parameter for special functions.

  • "first" - show the first page
  • "prev" - show the previous page
  • "next" - show the next page
  • "last" - show the last page

You can alternatively pass a callback to this function to decide what to do in this scenario, the callback should take two arguments, the first is the current page number, the second is the maximum page number. It should return the page that should be loaded, this can either be am integer or one of the strings outlined above

var table = new Tabulator("#example-table", {
    pagination:true, //enable pagination
    paginationOutOfRange:function(currentPage, maxPage){
        //currentPage - the current page number
        //maxPage - the maximum page number

        return currentPage > 10 ? "first" : "last";
    }
});

Callbacks

A range of callbacks are available for pagination. See the Pagination Callbacks section for more information.

Donate