Constructor

Commonly used

dataSource array | string | object | function

dataSource can be one of the following 4 formats.

1. Array

   an array data, eg:

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

2. Object

   an object that contained the array data, meanwhile, you should specify that array via locator: 'data'.

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

3. Function

   a function that will indicate the array data.

   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 your data, and then call done to return the array data.

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

4. URL

   Query data items for each paging from a remote server via Ajax.

   Usually you will use it with a locator to specify the location of the array containing data items within the response. The full response of the Ajax request is available as the originalResponse property of the pagination object passed to callback.

   /test.json

   For each pagination request, these two parameters pageNumber pageSize will be appended to the request url. You can customize their names via alias.

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

locator string | function (default data)

When the data source is not an array type, this option is used to indicate the position of the 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:

Provides a custom function to find the position of the array data.

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

The data got via Ajax also follow this rule.

totalNumber number (default 0)

When the dataSource is an URL, you should pass a totalNumber to specify the total number of data items (or via totalNumberLocator). OtherWise, it will not take effect as total number will be calculated automatically.

totalNumberLocator function(response)

Useful when the dataSource is an URL, and you expect specifies one of the field value in the request's response as the totalNumber.

Note: Pagination will ignore totalNumber option when totalNumberLocator specified.

See demo

pageNumber number (default 1)

Default page number at initialization.

pageSize number (default 10)

Number of data items per page.

pageRange number (default 2)

pageRange defines a range of pages that should be display around current page. For example, if current page number is 6 and pageRange is set to 2, then pagination bar will be displayed as like this '1 ... 4 567 8 ... 11 12'.

If you want to show all pages, just set it to null.

callback function(data, pagination)

Used to customize item's innerHTML, will be invoked on each paging.

To make it easier to maintain, you'd better to use templating engine such as Handlebars and Undercore.template.

it takes the resulting data and page number and pageSize as its arguments:

callback: function(data, pagination){ ... }

pagination object contains the following props:

alias object

Used to customize the name of pageNumber and pageSize when querying data items of the current page from remote server via Ajax.

For example：

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

The Ajax request will be sent with the new query names:

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

Display control

showPrevious boolean (default true)

Display the previous button.

showNext boolean (default true)

Display the next button.

showPageNumbers boolean (default true)

Display page number buttons.

showSizeChanger boolean (default false)

Display size changer.

See demo

sizeChangerOptions boolean (default [10, 20, 50, 100])

Specifies options for the size selector. Default is [10, 20, 50, 100].

showNavigator boolean (default false)

Display the navigator.

showGoInput boolean (default false)

Display the 'Go' input box.

showGoButton boolean (default false)

Display the 'Go' button.

hideFirstOnEllipsisShow boolean (default false)

To hide the first page number button when ellipsis showed.

hideFirstOnEllipsisShow: true,
pageRange: 1,
totalNumber: 100,
pageSize: 10

Follow the settings above, the pagination bar will be "... 4 5 6 ... 10".

hideLastOnEllipsisShow boolean (default false)

To hide the last page number when ellipsis showed.

hideLastOnEllipsisShow: true,
pageRange: 1,
totalNumber: 100,
pageSize: 10

Follow the settings above, the pagination bar will be "1 ... 4 5 6 ...".

autoHidePrevious boolean (default false)

To hide the previous button when current page number is the first.

See demo

autoHideNext boolean (default false)

To hide the next button when current page number is the last.

See demo

Style

classPrefix string

Prefixes class name of pagination elements. Default is paginationjs.

className string

Additional css class(es) for the root pagination element.

activeClassName string

CSS class(es) for the active button. Default is active.

disableClassName string

CSS class(es) for the disabled buttons. Default is disabled.

ulClassName string

CSS class(es) for the inner "ul" element.

pageClassName string

CSS class(es) for the page buttons.

prevClassName string

CSS class(es) for the "Previous" button.

nextClassName string

CSS class(es) for the "Next" button.

Customizable text

prevText string

Custom label for the Previous button. Default is «. Which is the symbol '«'.

nextText string

Custom label for the Next button. Default is ». Which is the symbol '»'.

ellipsisText string

Custom label for the ellipsis button. Default is ....

goButtonText string

Custom label for the Go button. Default is Go.

formatNavigator string | function(currentPage, totalPage, totalNumber)

Formats the navigator according to the specified variables. Accepts a string or a function that return those strings. Default is Total <%= totalNumber %> items.

The following are the available template variables:

• currentPage Current page number.
• totalPage Total pages.
• totalNumber Total number of data items.
• rangeStart Range start of current page.
• rangeEnd Range end of current page.

For example, total 195 data items and 20 items per page:

• <%= rangeStart %>-<%= rangeEnd %> of <%= totalNumber %> items => 1-20 of 195 items
• Total <%= totalNumber %> items => Total 195 items
• <%= currentPage %> / <%= totalPage %> => 1 / 10

See demo

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

Formats the Go input according to the specified variables. Accepts a string or a function that return those strings. Default is <%= input %>.

<%= 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 class name of the input contains J-paginationjs-go-pagenumber.

The following are the available template variables:

• input
• currentPage
• totalPage
• totalNumber

See demo

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

Formats the Go button according to the specified variables. Accepts a string or a function that return those strings. Default is <%= button %>.

<%= 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 class name of the button contains J-paginationjs-go-button.

The following are the available template variables:

• button
• currentPage
• totalPage
• totalNumber

header string | function(currentPage, totalPage, totalNumber)

Prepend extra contents to the pagination buttons. Accepts a string or a function that will return the extra contents.

The following are the available template variables:

• currentPage
• totalPage
• totalNumber

footer string | function(currentPage, totalPage, totalNumber)

Append extra contents to the pagination buttons. Accepts a string or a function that will return the extra contents.

The following are the available template variables:

• currentPage
• totalPage
• totalNumber

Utilities

formatResult function(data)

Formats the data items of current page before callback invoked.

In this function, you should return a result array, alse you can process the original data directly.

See demo

formatAjaxError function(jqXHR, textStatus, errorThrown)

A function to be called if the dataSource is an URL and request fails.

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

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

ajax object | function

Used to customize configuration for the built-in Ajax function. it must be parameter-compatible with $.ajax. Useful when you want to fetch data items from a remote server.

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

ajaxFunction function(settings)

A function to use as a replacement for $.ajax(). This function will be called with a single object parameter containing the same parameters as $.ajax(). Use this to implement a custom ajax function for pagination. The provided function must call either settings.success(response) where response is the returned data array or settings.error(jqXHR, textStatus, errorThrown). The parameters for the error function are passed to the formatAjaxError function if one is provided. These are the same parameters provided by the built-in Ajax function.

triggerPagingOnInit boolean (default true)

Determines whether to trigger the default pagination at initialization.

If you have already set innerHTML for the first page before Pagination initialization, you can set this option to false to prevent unnecessary paging once.

resetPageNumberOnInit boolean (default true)

Reset page number to 1 when Pagination initialized/reinitialized and dataSource is an URL.

hideOnlyOnePage boolean (default false)

Determines whether to hide pagination when there is only one page.

onError function(errorThrown, errorType)

A function to be called if error thrown when rendering pagination. The function gets passed two arguments: The error object and the error type.

Methods

After Pagination intialized, you can change the behavior of the .pagination through the following supported methods.

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

container.pagination('previous');

previous

Go to the previous page.

next

Go to the next page.

go

Go to the custom page. There is 2 ways:

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

you can also provide a callback to customize item's innerHTML of the target page. For example:

container.pagination('go', 8, function(data, pagination){
    // template method of yourself
})

Follow the code above, Pagination will use your callback function instead of the default callback function on this paging.

disable

To disable the pagination.

Note: If the dataSource is an URL, Pagination will be automatically set to disabled before sending the request, and enable will be automatically invoked after the request completes.

enable

To enable the pagination.

show

To display the pagination.

hide

To hide the pagination.

destroy

To destroy the pagination.

getCurrentPageNum number

Get current page number.

getTotalPage number

Get total page.

getCurrentPageData array

Get data items of current page.

isDisabled function

Whether pagination has been disabled.

Events

Pagination allows you to register all events for the lifetime of a paging behavior.

There are 2 ways: as callbacks or as plugin hooks.

Register events as callbacks:

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

Register events as plugin hooks:

var container = $('#example2');

container.pagination({
    dataSource: [1, 2, 3],
    pageSize: 1
});

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

In this way, the hook can be added before Pagination initialized.

beforeInit function

Fired before Pagination instance initialized. Return false will stop the initialization.

beforeRender function(isForced)

Fired before Pagination bar rendering. Parameters:

isForced is true if the rendering is triggered on paging and false if it is triggered at initialization.

beforePaging function

Fired before paging.

beforeSizeSelectorChange function

Fired before the size selector changed.

beforeDestroy function

Fired before pagination destroyed.

beforeDisable function

Fired before pagination disabled.

beforeEnable function

Fired before pagination enabled.

beforePreviousOnClick function

Fired before the 'previous' button clicked.

beforePageOnClick function

Fired before page button clicked.

beforeNextOnClick function

Fired before the 'next' button clicked.

beforeGoInputOnEnter function

Fired before Enter pressed on the 'Go' input.

beforeGoButtonOnClick function

Fired before the 'Go' button clicked.

afterInit function

Fired after Pagination initialized.

afterRender function

Fired after Pagination bar rendered. Parameters:

isForced is true if the rendering is triggered on paging and false if it is triggered at initialization.

afterPaging function

Fired after paging.

afterSizeSelectorChange function

Fired after the size selector changed.

afterDestroy function

Fired after pagination destroyed.

afterDisable function

Fired after pagination disabled.

afterEnable function

Fired after pagination enabled.

afterPreviousOnClick function

Fired after the 'previous' button clicked.

afterPageOnClick function

Fired after page button clicked.

afterNextOnClick function

Fired after the 'next' button clicked.

afterGoInputOnEnter function

Fired after Enter pressed on the 'Go' input.

afterGoButtonOnClick function

Fired after the 'Go' button clicked.

afterIsFirstPage function

Fired after current page number is the first.

afterIsLastPage function

Fired after current page number is the last.

Theme

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

First, you should link the css file in the header tag of HTML:

<link rel="stylesheet" href="{yourAssetsServer}/pagination.css" />

css & less file: pagination.css pagination.less

For example, the blue theme:

className: 'paginationjs-theme-blue'

small & blue:

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

big & blue:

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

If you want to fully customize the style, you can add custom-paginationjs to the className option.

Configuring Defaults

Pagination.js 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.