Fork me on GitHub
Pagination.js Documentation

Constructor

Commonly used

dataSource array | string | object | function

Data source, ultimately an array will be provided for Pagination.

Data source supports 4 formats.

  1. Array

    Directly providing an array, such as:

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

    Provide an object, which will contain an array, and the array can be specified via locator: 'data'.

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

    Provide a custom function, use done to return an array, can achieve above 2 ways.

     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, use done to return asynchronous data.

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

    Provide a URL, returns data via Ajax, each request returns one page of data, the data returned can also be located by locator.

    If URL is one type of File, HTTP or HTTPS protocol, will using jsonp to send requests, otherwise Ajax.

     /test.json
    

    For each pagination request, two parameters pageNumber and pageSize will be added, you can also use alias to specify the parameter's name.

     /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 the return is an Object, then you need to specify that array.

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

Used as a string:

locator: 'data':

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

locator uses to-function, so you may 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, find the array position, and return.

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

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

totalNumber number (default 1)

Total entries, This option must be specified when pagination is asynchronous.

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

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
totalPage number Total 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 pageaNumber 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

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

String containing the template variables or a function that returns such a string.

Provide 3 template variables.

See demo

formatGoInput string | function

Format template for the 'Go' input box. Default is <%= input %>.

String containing the template variables or a function that returns such a string.

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

Provide 4 template variables.

See demo

formatGoButton string | function

Format template for the 'Go' button. Default is <%= button %>.

String containing the template variables or a function that returns such a string.

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

Provide 4 template variables.

header string | function

Custom header content. header may be a string or a function.

Provide 3 template variables.

footer string | function

Custom footer content. footer may be a string or a function.

Provide 3 template variables.

pageLink string

Page link.

Utilities

formatResult function(data)

Provide a custom function, processing result data before the callback function called.

Return an processed array, or process the passed data array directly.

See demo

formatAjaxError function(jqXHR, textStatus, errorThrown)

Provide a custom function, for rendering the error message.

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

ajax object

Customized configuration for the built-in Ajax function. 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.

in some cases, you may load the content of the first page with AJAX and the content already showed before you initialize the pagination, you should set this option to false.

There are anthor usage, load the content of the second page by default, for example:

triggerPagingOnInit: true,
pageNum: 2

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