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", {
    height:"292px",
    layout:"fitColumns",
    pagination:"local",
    paginationSize:6,
    movableColumns:true,
    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", align:"center", width:100},
        {title:"Favourite Color", field:"col"},
        {title:"Date Of Birth", field:"dob", align:"center", sorter:"date"},
        {title:"Driver", field:"car", align:"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 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:"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
});

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 paginationDataSent option to set alternative parameter names.

var table = new Tabulator("#example-table", {
    pagination:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    paginationDataSent:{
        "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 paginationDataReceived option to set alternative parameter names.

var table = new Tabulator("#example-table", {
    pagination:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    paginationDataReceived:{
        "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.

To enable local pagination set the pagination option to local.

var table = new Tabulator("#example-table", {
    pagination:"local", //enable local 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:"local", //enable local pagination.
    paginationSize:5, // this option can take any positive integer value (default = 10)
});

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:"local", //enable local pagination.
});

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.

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:"local",
    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
});

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:"local",
    paginationAddRow:"table", //add rows relative to the table
});

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 successfuly 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 successfuly 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 successfuly updated
})
.catch(function(error){
    //handle error loading data
});

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

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

Callbacks

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