Fork me on GitHub
Pagination.js Documentation

Constructor

Commonly used

dataSource array | string | object | function

Specify the data source of the pagination.

dataSource supports 4 formats.

  1. Array

    Directly provide an array, such as:

     ['1', '2', '3', '4']
    
  2. Object

    Provide an object contained an array, that array can be specified via locator: 'data'.

     {
        data: ['1', '2', '3', '4']
     }
    
  3. Function

    Provide a custom function.

     dataSource: function(done){
        var result = [];
        for (var i = 1; i < 196; i++) {
            result.push(i);
        }
        done(result);
     }
    

    You can also send a request to get data, invoke done to return the data source.

     dataSource: function(done) {
        $.ajax({
            type: 'GET',
            url: '/test.json',
            success: function(response) {
                done(response);
            }
        });
     }
    
  4. URL

    Indicate the data source via Ajax, each request returns one page of data, the data returned can be located by locator.

    Pagination will using jsonp to send requests while URL is file, HTTP or HTTPS protocol, otherwise Ajax.

     /test.json
    

    For each pagination request, these two parameters pageNumber pageSize will be appended to the request url. The parameter's name can be specified by alias.

     /test.json?pageNumber=2&pageSize=10
    

locator string | function (default data)

In general, data source is an array, and it can be processed directly by Pagination. But if an Object is returned, then you need to specify that array.

This option is used to manually modify the location of that array in the data source.

Using as a string:

locator: 'data':

{
    data: ['1', '2', '3', '4']
}

locator uses to-function, so you can use dot notation to traverse the result array, such as locator: 'a.b':

{
    a: {b: ['1', '2', '3', '4']}
}

Using as a function:

Provide a custom function to find the position of that array.

locator: function() {
    // find data and return
    return 'a.b';
}

Please note that the data got via Ajax will apply the same rules.

totalNumber number (default 0)

Specify the total number of entries in advance (optional), it can be used when pagination is in asynchronous mode.

Note: This option only has effect in Pagination constructor and only if dataSource option is a URL.

totalNumberLocator function(response)

Find totalNumber from remote response, only available when dataSource is a string.

Note: Specify totalNumberLocator will ignore the totalNumber option.

See demo

pageNumber number (default 1)

Specify the page number at initialization.

pageSize number (default 10)

Entries of per page.

pageRange number (default 2)

Range of visible page number, this means that the amount on both sides of the selected page. For example, if the selected page number is 6, and pageRange is set to 2, then the pagination bar will be displayed as like this '1 ... 4 567 8'.

callback function(data, pagination)

Callback of each paging. Useful for processing the result data before rendered.

The callback function will get two parameters

callback: function(data, pagination) { ... }
Parameter Type Description
data array data of selected page
pagination object pagination data

pagination object contains the following custom properties:

Property Type Description
pageNumber number The selected page number
pageRange number Visible page number range
pageSize number Entries of per page
totalNumber number Total entries
el jQuery object Pagination element
direction number Pagination direction, -1 means forward, 1 means backward, 0 means current is at initialization.

alias object

Used to manually modify the parameters of the Ajax request. Useful for asynchronous pagination.

Here's the example:

alias: {
    pageNumber: 'pageNum',
    pageSize: 'limit'
}

When the Ajax request sent, will replace the defaults pageNumber and pageSize.

/test.json?pageNum=2&limit=10

Display control

showPrevious boolean (default true)

Determines whether to display the previous button.

showNext boolean (default true)

Determines whether to display the next button.

showPageNumbers boolean (default true)

Determines whether to display the page number buttons.

showNavigator boolean (default false)

Determines whether to display the navigator.

showGoInput boolean (default false)

Determines whether to display the 'Go' input box.

showGoButton boolean (default false)

Determines whether to display the 'Go' button.

showFirstOnEllipsisShow boolean (default true)

Determines whether to display the first page number buttons when the ellipsis was displayed.

showBeginingOnOmit: false,
pageRange: 1,
totalNumber: 100,
pageSize: 10

The above settings, pagination bar will be displayed as like this "... 4 5 6 ... 10".

showLastOnEllipsisShow boolean (default true)

Determines whether to display the last page number when the ellipsis was displayed.

showEndingOnOmit: false,
pageRange: 1,
totalNumber: 100,
pageSize: 10

The above settings, for example, pagination bar will be displayed as like this "1 ... 4 5 6 ...".

autoHidePrevious boolean (default false)

Determines whether to display the previous button when the selected page number was the first page.

See demo

autoHideNext boolean (default false)

Determines whether to display the next button when the selected page number was the last page.

See demo

Style

classPrefix string

Style prefix. Default is pagination.

className string

Additional style class(es) for the Pagination element.

activeClassName string

ClassName of the selected page number button. Default is active.

disableClassName string

ClassName of the disabled page number button. Default is disabled.

ulClassName string

ClassName of the 'ul' element that contained by the Pagination element.

Customizable text

prevText string

The text to display for the previous button. Default is &laquo;. That is the symbol '«'.

nextText string

The text to display for the next button. Default is &raquo;. That is the symbol '»'.

ellipsisText string

The text to display for the ellipsis button. Default is ....

goButtonText string

The text to display for the Go button. Default is Go.

formatNavigator string | function(currentPage, totalPage, totalNumber)

Format the navigator from the template. Default is <%= currentPage %> / <%= totalPage %>.

A string contained template variables or a function that returns such a string.

There are 3 template variables.

See demo

formatGoInput string | function(input, currentPage, totalPage, totalNumber)

Format the "Go" input from the template. Default is <%= input %>.

A string contained template variables or a function that returns such a string.

<%= input %> is equivalent to <input type= "text" class= "J-paginationjs-go-pagenumber" >, therefore, you can also customize an input element yourself, just ensure that the element has a J-paginationjs-go-pagenumber class.

There are 4 template variables.

See demo

formatGoButton string | function(button, currentPage, totalPage, totalNumber)

Format the "Go" button from the template. Default is <%= button %>.

A string contained template variables or a function that returns such a string.

<%= button %> is equivalent to <input type="button" class="J-paginationjs-go-button">, therefore, you can also customize an button element yourself, just ensure that the element has a J-paginationjs-go-button class.

There are 4 template variables.

header string | function(currentPage, totalPage, totalNumber)

Customize the header content. header may be a string or a function.

There are 3 template variables.

footer string | function(currentPage, totalPage, totalNumber)

Customize the footer content. footer may be a string or a function.

There are 3 template variables.

Utilities

formatResult function(data)

Used to process result data before callback invoked.

You should return an array processed by this function, you can also process data directly.

See demo

formatAjaxError function(jqXHR, textStatus, errorThrown)

A function for rendering the error message.

formatAjaxError: function(jqXHR, textStatus, errorThrown) { ... }

ajax object

Used to customize configuration for the built-in Ajax function. it must be parameter-compatible with $.ajax. Usuful for the asynchronous pagination.

Parameter Type Description
type string The type of request to make (e.g. "POST", "GET", "PUT"); Default is GET.
dataType string Data type for the request. xml, json, jsonp, other formats supported by jQuery. Default is json.
data object By default, pageNumber and pageSize will be sent. If you need additional data to be sent to the server. set this option. For example: { ajax: { data: {dbType: 'oracle'} } }.
cache boolean If set to false, it will force requested pages not to be cached by the browser. Default is true.
async boolean By default, all requests are sent asynchronously. If you need synchronous requests, set this option to false. Default is true.
beforeSend function A pre-request callback function that can be used to modify the jqXHR object before it is sent. Returning false in the beforeSend function will cancel the request.

For more info on the parameters, refer to the JQuery API Documentation.

triggerPagingOnInit boolean (default true)

Determines whether to trigger default pagination at initialization.

you may want to load the first page with AJAX, while the content has already been loaded before the pagination initialized. In this situation, you should set this option to false.

hideWhenLessThanOnePage boolean (default false)

Determines whether to hide pagination when less than one page.

inlineStyle boolean (default true)

Determines whether to use inline styles.

Pagination comes with style content, by default, the style content will be inserted in an style element to the head element.

If you think the use of the link would be better, you can set this option to false to prevent insertion behavior, and references your css file to the link element.

The default styles: pagination.css pagination.less, but you can easily write these styles to apply your own.

Note, make sure that use pagination-with-styles.js before set this option.

Note, this will not be supported from v2.0.6, please use Link to import css.

Methods

After Pagination is constructed, you can modify the behavior using the available public methods.

var container = $('#example');
container.pagination({ ... });
container.pagination('previous');

previous

Go to the previous page.

next

Go to the next page.

go

Go to a custom page. There are 2 ways:

container.pagination('go', 8)
container.pagination(8)

Note, after set a custom function, will no longer call the default callback function.

disable

Disables the pagination.

Note: before the asynchronous pagination request sent, pagination will automatically call this method, and automatically call enable method to enables the pagination after the request was completed successfully.

enable

Enables the pagination.

show

Show the pagination.

hide

Hide the pagination.

destroy

Destroy the pagination instance.

getSelectedPageNum number

Get selected page number.

getTotalPage number

Get total page.

getSelectedPageData array

Get selected page data.

isDisabled function

Whether pagination was be disabled.

Events

Pagination events are the common interface that function in 2 ways: as callbacks and as plugin hooks.

Using events as callbacks:

var container = $('#example');
    container.pagination({
    afterRender: function() {
        // function body
    }
});

Using events as plugin hooks:

var container = $('#example');
container.pagination({
    dataSource: [1, 2, 3],
    pageSize: 1
});

// add some hooks
container.addHook('afterRender', function() {
    // function body
});

Note, the hook can be added before Pagination initialized, can also be added after Pagination initialized.

beforeInit function

Invoked before initializing a new pagination instance. Return false will stop the initialization.

beforeRender function

Invoked before rendering pagination bar. Parameters:

isForced is true if rendering was triggered by a paging; or false if rendering was triggered by Pagination initialization.

beforePaging function

Invoked before paging.

beforeDestroy function

Invoked before destroying pagination instance.

beforeDisable function

Invoked before disabling paging.

beforeEnable function

Invoked before enabling paging.

beforePreviousOnClick function

Invoked before clicking 'previous' button.

beforePageOnClick function

Invoked before clicking page number button.

beforeNextOnClick function

Invoked before clicking 'next' button.

beforeGoInputOnEnter function

Invoked before a Enter pressed on the 'Go' input.

beforeGoButtonOnClick function

Invoked before clicking 'Go' button.

afterInit function

Invoked after initializing a new pagination instance.

afterRender function

Invoked after rendering pagination bar. Parameters:

isForced is true if rendering was triggered by a paging; or false if rendering was triggered by Pagination initialization.

afterPaging function

Invoked after paging.

afterDestroy function

Invoked immediately after destroying pagination instance.

afterDisable function

Invoked after disabling paging.

afterEnable function

Invoked after enabling paging.

afterPreviousOnClick function

Invoked after clicking 'previous' button.

afterPageOnClick function

Invoked after clicking page number button.

afterNextOnClick function

Invoked after clicking 'next' button.

afterGoInputOnEnter function

Invoked after a Enter pressed on the 'Go' input.

afterGoButtonOnClick function

Invoked after clicking 'Go' button.

afterIsFirstPage function

Invoked when the selected page number is the first.

afterIsLastPage function

Invoked when the selected page number is the last.

Skin

Pagination comes with 5 sets of default skins, but you can fully customize your own skin.

The blue skin, for example, it can be used:

className: 'paginationjs-theme-blue'

The small blue skin:

className: 'paginationjs-theme-blue paginationjs-small'

The big blue skin:

className: 'paginationjs-theme-blue paginationjs-big'

If you need a custom style, you can add CSS class custom-paginationjs.

Configuring Defaults

Pagination exposes its default options via the $.fn.pagination.defaults object. Properties changed in this object (same properties configurable through the constructor) will take effect for every instance created after the change.

For example:

$.extend($.fn.pagination.defaults, {
    pageSize: 20
})

After the change, all the new pagination instances's pageSize will be set to 20.


Help improve these docs.

Open an issue or pull request.

Top