GridView has a core feature of being able to simplify filter rows just by putting an additional row below the header row.

Filters are mainly text input but in general they can be any type of control and we can customize them as much as we want.

Filters can be activated by filling out the GridView widget property filterModel with an instance of the model class and automatically a new row will be created below the header, containing working text inputs.

Filter text inputs have a name attribute filled with the model class name, which includes the field name. In this way, we will pass data to a controller, including everything in a single array; a variable that can easily be used to populate a search model massively.

Let's create an example with the reservations grid.

We will fill out the filterModel property to apply filters to GridView, for example:

<?= yiigridGridView::widget([
    ...
    'filterModel' => $searchModel,
    ...        
?>

Here, $searchModel is an instance of the Reservation model class that we will pass to the view from the grid action of ReservationsController.

Now let's create actionGrid() in ReservationsController in basic/controllers/ReservationsController.php:

    <?php

public function actionGrid()
    {
        $query = appmodelsReservation::find();

        $searchModel = new appmodelsReservation();
        if(isset($_GET['Reservation']))
        {
            $searchModel->load( Yii::$app->request->get() );
            
            $query->andFilterWhere([
                'id' => $searchModel->id,
                'customer_id' => $searchModel->customer_id,
                'room_id' => $searchModel->room_id,
                'price_per_day' => $searchModel->price_per_day,
            ]);
        }
        
        $dataProvider = new yiidataActiveDataProvider([
            'query' => $query,
            'pagination' => [
                'pageSize' => 10,
            ],
        ]);
        
        
        return $this->render('grid', [ 'dataProvider' => $dataProvider, 'searchModel' => $searchModel ]);
        
    }

The $searchModel instance is filled with the content of $_GET['Reservation'], in line:

            $searchModel->load( Yii::$app->request->get() );

Then, $query is updated with the content of non-null attributes.

Browse to http://hostname/basic/reservations/grid and type 2 in the Room ID column filter (the second column). This should be the output:

Using filters in the GridView widget

We can also choose to customize the way we render a filter. Imagine using the Room ID column filter as a drop-down list instead of an input textbox.

We only need to fill out the filter property of Room ID with dropDownList. It is advisable to use the Html helper class to render dropDownList using the activeDropDownList() method. The active prefix stands for ActiveRecord. This method dropDownList() requires three parameters: the model class, the attribute of the model class, and finally an array key-value where key is the value attribute of the <option> tag and value is the text of the <option> tag.

We will use yiihelpersArrayHelper to create the array key-value, where the key is the id attribute of the model and the value is the return value of a callback function.

This is how the file in basic/views/reservations/grid.php changes:

<?php
$roomsFilterData = yiihelpersArrayHelper::map( appmodelsRoom::find()->all(), 'id', function($model, $defaultValue) {
    return sprintf('Floor: %d - Number: %d', $model->floor, $model->room_number);
});
?>

<?= yiigridGridView::widget([
    'dataProvider' => $dataProvider,
    'filterModel' => $searchModel,
    'columns' => [
        'id',
         
        [
            'header' => 'Room',
            'filter' => Html::activeDropDownList($searchModel, 'room_id', $roomsFilterData, ['prompt' => '--- all']),
            'content' => function($model) {
                return $model->room->floor;
            }
        ],

This is the expected output:

GridView with the dropdown list filter