Yii2 ListView Example: Customizing Pagination

By:   –  Last updated:   –  #yii2 ·  #php

Code Theme [Dark]

Content Overview [Hide]

Default pager of Yii2 ListView is an instance of yii\widgets\LinkPager class using CSS style of Bootstrap pagination component. Customization of ListView pager is quite simple.

1. Customize Pager Labels

It's quite straightforward to customize text labels of navigating links in ListView pagination.

ListView::widget([
    'dataProvider' => $listDataProvider,
    'pager' => [
        'firstPageLabel' => 'first',
        'lastPageLabel' => 'last',
        'prevPageLabel' => 'previous',
        'nextPageLabel' => 'next',
    ],
])

Because Yii2 has built-in Bootstrap assets bundle, you can use Glyphicons font icon as label directly.

For example, using font icon <span class="glyphicon glyphicon-chevron-left"></span> and <span class="glyphicon glyphicon-chevron-right"></span> as previous and next label.

ListView::widget([
    'dataProvider' => $listDataProvider,
    'pager' => [
        'firstPageLabel' => 'first',
        'lastPageLabel' => 'last',
        'prevPageLabel' => '<span class="glyphicon glyphicon-chevron-left"></span>',
        'nextPageLabel' => '<span class="glyphicon glyphicon-chevron-right"></span>',
    ],
])

2. Number of Pager Buttons

The maxButtonCount property of pager controls the number of pager item buttons that will be displayed.

ListView::widget([
    'dataProvider' => $listDataProvider,
    'pager' => [
        'firstPageLabel' => 'first',
        'lastPageLabel' => 'last',
        'prevPageLabel' => 'previous',
        'nextPageLabel' => 'next',
        'maxButtonCount' => 3,
    ],
])

As shown in following screenshot, Yii2 ListView will only render 3 pager buttons.

customize_yii_listview_maxButtonCount

3. Customize CSS Style

By deafult Yii2 ListView pagination uses Bootstrap CSS style. There are two ways to customize CSS style of ListView pagination.

3.1 Add Custom CSS Class

We can add customizing css classes to pager links and navigating links, then style them with our own CSS style.

ListView::widget([
    'dataProvider' => $listDataProvider,
    'pager' => [
        'firstPageLabel' => 'first',
        'lastPageLabel' => 'last',
        'prevPageLabel' => 'previous',
        'nextPageLabel' => 'next',
        'maxButtonCount' => 3,
        
        // Customzing options for pager container tag
        'options' => [
            'tag' => 'div',
            'class' => 'pager-wrapper',
            'id' => 'pager-container',
        ],
        
        // Customzing CSS class for pager link
        'linkOptions' => ['class' => 'mylink'],
        'activePageCssClass' => 'myactive',
        'disabledPageCssClass' => 'mydisable',
        
        // Customzing CSS class for navigating link
        'prevPageCssClass' => 'mypre',
        'nextPageCssClass' => 'mynext',
        'firstPageCssClass' => 'myfirst',
        'lastPageCssClass' => 'mylast',
    ],
])

3.2 Customize Bootstrap Pagination Style

Because the default style of ListView pagination uses Bootstrap pagination component, we can customize Bootstrap directly.

How to customize Bootstrap CSS style? Please refer to the article: Customize Bootstrap Using bootstrap-sass and Gulp

4. Furthermore: Custom Pager Widget

If you want to custom LinkPager widget itself, refer to Yii2 ListView: Create Custom LinkPager Class.