# ListView

> The ListView widget is used to display data from data provider.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [widgets](/docs/api/yii/widgets/index.md) › ListView

| class | `yii\widgets\ListView` |
| --- | --- |
| Extends | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) » [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) » [`yii\base\Component`](/docs/api/yii/base/component/index.md) » [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\base\ViewContextInterface`](/docs/api/yii/base/viewcontextinterface/index.md), [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Since | 2.0 |
| Source | [`framework/widgets/ListView.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/widgets/ListView.php#L25) |

The ListView widget is used to display data from data
provider. Each data model is rendered using the view
specified.

For more details and usage information on ListView, see the [guide article on data widgets](/docs/guide/output-data-widgets/index.md).

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| [`$afterItem`](#property-afterItem) | [`Closure`](https://www.php.net/manual/en/class.closure.php)`\|null` | An anonymous function that is called once AFTER rendering each data model. Default: `null`. Available since 2.0.11. | `ListView` |
| <span id="property-autoIdPrefix"></span>[`$autoIdPrefix`](/docs/api/yii/base/widget/index.md#property-autoIdPrefix) static | `string` | The prefix to the automatically generated widget IDs. Default: `'w'`. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| [`$beforeItem`](#property-beforeItem) | [`Closure`](https://www.php.net/manual/en/class.closure.php)`\|null` | An anonymous function that is called once BEFORE rendering each data model. Default: `null`. Available since 2.0.11. | `ListView` |
| <span id="property-behaviors"></span>[`$behaviors`](/docs/api/yii/base/component/index.md#property-behaviors) read-only | `array<`[`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md)`<static>>` | List of behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="property-dataProvider"></span>[`$dataProvider`](/docs/api/yii/widgets/baselistview/index.md#property-dataProvider) | [`yii\data\DataProviderInterface`](/docs/api/yii/data/dataproviderinterface/index.md) | The data provider for the view. Default: `null`. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="property-emptyText"></span>[`$emptyText`](/docs/api/yii/widgets/baselistview/index.md#property-emptyText) | `string\|false\|null` | The HTML content to be displayed when [`$dataProvider`](/docs/api/yii/widgets/baselistview/index.md#property-dataProvider) does not have any data. Default: `null`. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="property-emptyTextOptions"></span>[`$emptyTextOptions`](/docs/api/yii/widgets/baselistview/index.md#property-emptyTextOptions) | `array` | The HTML attributes for the emptyText of the list view. Default: `['class' => 'empty']`. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="property-id"></span>[`$id`](/docs/api/yii/base/widget/index.md#property-id) | `string` | Id of the widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| [`$itemOptions`](#property-itemOptions) | `array\|`[`Closure`](https://www.php.net/manual/en/class.closure.php) | The HTML attributes for the container of the rendering result of each data model. Default: `[]`. | `ListView` |
| [`$itemView`](#property-itemView) | `string\|callable` | The name of the view for rendering each data item, or a callback (e.g. an anonymous function) for rendering each data item. Default: `null`. | `ListView` |
| <span id="property-layout"></span>[`$layout`](/docs/api/yii/widgets/baselistview/index.md#property-layout) | `string` | The layout that determines how different sections of the list view should be organized. Default: `"{summary}\n{items}\n{pager}"`. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| [`$options`](#property-options) | `array` | The HTML attributes for the container tag of the list view. Default: `['class' => 'list-view']`. | `ListView` |
| <span id="property-pager"></span>[`$pager`](/docs/api/yii/widgets/baselistview/index.md#property-pager) | `array` | The configuration for the pager widget. Default: `[]`. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="property-separator"></span>`$separator` | `string` | The HTML code to be displayed between any two consecutive items. Default: `"\n"`. | `ListView` |
| <span id="property-showOnEmpty"></span>[`$showOnEmpty`](/docs/api/yii/widgets/baselistview/index.md#property-showOnEmpty) | `bool` | Whether to show an empty list view if [`$dataProvider`](/docs/api/yii/widgets/baselistview/index.md#property-dataProvider) returns no data. Default: `false`. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="property-sorter"></span>[`$sorter`](/docs/api/yii/widgets/baselistview/index.md#property-sorter) | `array` | The configuration for the sorter widget. Default: `[]`. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="property-summary"></span>[`$summary`](/docs/api/yii/widgets/baselistview/index.md#property-summary) | `string\|null` | The HTML content to be displayed as the summary of the list view. Default: `null`. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="property-summaryOptions"></span>[`$summaryOptions`](/docs/api/yii/widgets/baselistview/index.md#property-summaryOptions) | `array` | The HTML attributes for the summary of the list view. Default: `['class' => 'summary']`. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="property-view"></span>[`$view`](/docs/api/yii/base/widget/index.md#property-view) | [`yii\web\View`](/docs/api/yii/web/view/index.md) | The view object that can be used to render views or view files. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| [`$viewParams`](#property-viewParams) | `array` | Additional parameters to be passed to [`$itemView`](/docs/api/yii/widgets/listview/index.md#property-itemView) when it is being rendered. Default: `[]`. | `ListView` |
| <span id="property-viewPath"></span>[`$viewPath`](/docs/api/yii/base/widget/index.md#property-viewPath) read-only | `string` | The directory containing the view files for this widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-__construct"></span>[`__construct()`](/docs/api/yii/base/baseobject/index.md#method-__construct) | Constructor. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__call"></span>[`__call()`](/docs/api/yii/base/component/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__clone"></span>[`__clone()`](/docs/api/yii/base/component/index.md#method-__clone) | This method is called after the object is created by cloning an existing one. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/component/index.md#method-__get) | Returns the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/component/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/component/index.md#method-__set) | Sets the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/component/index.md#method-__unset) | Sets a component property to be null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-afterRun"></span>[`afterRun()`](/docs/api/yii/base/widget/index.md#method-afterRun) | This method is invoked right after a widget is executed. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-attachBehavior"></span>[`attachBehavior()`](/docs/api/yii/base/component/index.md#method-attachBehavior) | Attaches a behavior to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-attachBehaviors"></span>[`attachBehaviors()`](/docs/api/yii/base/component/index.md#method-attachBehaviors) | Attaches a list of behaviors to the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-beforeRun"></span>[`beforeRun()`](/docs/api/yii/base/widget/index.md#method-beforeRun) | This method is invoked right before the widget is executed. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-begin"></span>[`begin()`](/docs/api/yii/base/widget/index.md#method-begin) static | Begins a widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-behaviors"></span>[`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) | Returns a list of behaviors that this component should behave as. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/component/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/component/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-className"></span>[`className()`](/docs/api/yii/base/baseobject/index.md#method-className) static | Returns the fully qualified name of this class. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-detachBehavior"></span>[`detachBehavior()`](/docs/api/yii/base/component/index.md#method-detachBehavior) | Detaches a behavior from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-detachBehaviors"></span>[`detachBehaviors()`](/docs/api/yii/base/component/index.md#method-detachBehaviors) | Detaches all behaviors from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-end"></span>[`end()`](/docs/api/yii/base/widget/index.md#method-end) static | Ends a widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-ensureBehaviors"></span>[`ensureBehaviors()`](/docs/api/yii/base/component/index.md#method-ensureBehaviors) | Makes sure that the behaviors declared in [`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) are attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBehavior"></span>[`getBehavior()`](/docs/api/yii/base/component/index.md#method-getBehavior) | Returns the named behavior object. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBehaviors"></span>[`getBehaviors()`](/docs/api/yii/base/component/index.md#method-getBehaviors) | Returns all behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getId"></span>[`getId()`](/docs/api/yii/base/widget/index.md#method-getId) | Returns the ID of the widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-getView"></span>[`getView()`](/docs/api/yii/base/widget/index.md#method-getView) | Returns the view object that can be used to render views or view files. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-getViewPath"></span>[`getViewPath()`](/docs/api/yii/base/widget/index.md#method-getViewPath) | Returns the directory containing the view files for this widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-hasEventHandlers"></span>[`hasEventHandlers()`](/docs/api/yii/base/component/index.md#method-hasEventHandlers) | Returns a value indicating whether there is any handler attached to the named event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/component/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/component/index.md#method-hasProperty) | Returns a value indicating whether a property is defined for this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-init"></span>[`init()`](/docs/api/yii/widgets/baselistview/index.md#method-init) | Initializes the view. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="method-off"></span>[`off()`](/docs/api/yii/base/component/index.md#method-off) | Detaches an existing event handler from this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-on"></span>[`on()`](/docs/api/yii/base/component/index.md#method-on) | Attaches an event handler to an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-render"></span>[`render()`](/docs/api/yii/base/widget/index.md#method-render) | Renders a view. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-renderEmpty"></span>[`renderEmpty()`](/docs/api/yii/widgets/baselistview/index.md#method-renderEmpty) | Renders the HTML content indicating that the list view has no data. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="method-renderFile"></span>[`renderFile()`](/docs/api/yii/base/widget/index.md#method-renderFile) | Renders a view file. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| [`renderItem()`](#method-renderItem) | Renders a single data model. | `ListView` |
| [`renderItems()`](#method-renderItems) | Renders all data models. | `ListView` |
| <span id="method-renderPager"></span>[`renderPager()`](/docs/api/yii/widgets/baselistview/index.md#method-renderPager) | Renders the pager. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="method-renderSection"></span>[`renderSection()`](/docs/api/yii/widgets/baselistview/index.md#method-renderSection) | Renders a section of the specified name. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="method-renderSorter"></span>[`renderSorter()`](/docs/api/yii/widgets/baselistview/index.md#method-renderSorter) | Renders the sorter. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="method-renderSummary"></span>[`renderSummary()`](/docs/api/yii/widgets/baselistview/index.md#method-renderSummary) | Renders the summary text. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="method-run"></span>[`run()`](/docs/api/yii/widgets/baselistview/index.md#method-run) | Runs the widget. | [`BaseListView`](/docs/api/yii/widgets/baselistview/index.md) |
| <span id="method-setId"></span>[`setId()`](/docs/api/yii/base/widget/index.md#method-setId) | Sets the ID of the widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-setView"></span>[`setView()`](/docs/api/yii/base/widget/index.md#method-setView) | Sets the view object to be used by this widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-trigger"></span>[`trigger()`](/docs/api/yii/base/component/index.md#method-trigger) | Triggers an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-widget"></span>[`widget()`](/docs/api/yii/base/widget/index.md#method-widget) static | Creates a widget instance and runs it. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| [`renderAfterItem()`](#method-renderAfterItem) protected | Calls [`$afterItem`](/docs/api/yii/widgets/listview/index.md#property-afterItem) closure, returns execution result. | `ListView` |
| [`renderBeforeItem()`](#method-renderBeforeItem) protected | Calls [`$beforeItem`](/docs/api/yii/widgets/listview/index.md#property-beforeItem) closure, returns execution result. | `ListView` |

## Events

| Event | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="event-EVENT_INIT"></span>[`EVENT_INIT`](/docs/api/yii/base/widget/index.md#event-EVENT_INIT) | [`yii\base\Event`](/docs/api/yii/base/event/index.md) | An event that is triggered when the widget is initialized via [`init()`](/docs/api/yii/base/widget/index.md#method-init). Event name: `'init'`. Available since 2.0.11. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="event-EVENT_BEFORE_RUN"></span>[`EVENT_BEFORE_RUN`](/docs/api/yii/base/widget/index.md#event-EVENT_BEFORE_RUN) | [`yii\base\WidgetEvent`](/docs/api/yii/base/widgetevent/index.md) | An event raised right before executing a widget. Event name: `'beforeRun'`. Available since 2.0.11. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="event-EVENT_AFTER_RUN"></span>[`EVENT_AFTER_RUN`](/docs/api/yii/base/widget/index.md#event-EVENT_AFTER_RUN) | [`yii\base\WidgetEvent`](/docs/api/yii/base/widgetevent/index.md) | An event raised right after executing a widget. Event name: `'afterRun'`. Available since 2.0.11. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |

## Property details

### $afterItem <span id="property-afterItem"></span>

```php
public Closure|null $afterItem = null
```

An anonymous function that is called once AFTER rendering each data model.

It should have the same signature as [`$beforeItem`](/docs/api/yii/widgets/listview/index.md#property-beforeItem).

The return result of the function will be rendered directly.
Note: If the function returns `null`, nothing will be rendered after the item.

**Since**

2.0.11

### $beforeItem <span id="property-beforeItem"></span>

```php
public Closure|null $beforeItem = null
```

An anonymous function that is called once BEFORE rendering each data model.

It should have the following signature:

```
function ($model, $key, $index, $widget)
```

- `$model`: the current data model being rendered
- `$key`: the key value associated with the current data model
- `$index`: the zero-based index of the data model in the model array returned by [`$dataProvider`](/docs/api/yii/widgets/baselistview/index.md#property-dataProvider)
- `$widget`: the ListView object

The return result of the function will be rendered directly.
Note: If the function returns `null`, nothing will be rendered before the item.

**Since**

2.0.11

### $itemOptions <span id="property-itemOptions"></span>

```php
public array|Closure $itemOptions = []
```

The HTML attributes for the container of the rendering result of each data model.

This can be either an array specifying the common HTML attributes for rendering each data item,
or an anonymous function that returns an array of the HTML attributes. The anonymous function will be
called once for every data model returned by [`$dataProvider`](/docs/api/yii/widgets/baselistview/index.md#property-dataProvider).
The "tag" element specifies the tag name of the container element and defaults to "div".
If "tag" is false, it means no container element will be rendered.

If this property is specified as an anonymous function, it should have the following signature:

```
function ($model, $key, $index, $widget)
```

### $itemView <span id="property-itemView"></span>

```php
public string|callable $itemView = null
```

The name of the view for rendering each data item, or a callback (e.g. an anonymous function) for rendering each data item.

If it specifies a view name, the following variables will
be available in the view:

- `$model`: mixed, the data model
- `$key`: mixed, the key value associated with the data item
- `$index`: integer, the zero-based index of the data item in the items array returned by [`$dataProvider`](/docs/api/yii/widgets/baselistview/index.md#property-dataProvider).
- `$widget`: ListView, this widget instance

Note that the view name is resolved into the view file by the current context of the [`$view`](/docs/api/yii/base/widget/index.md#property-view) object.

If this property is specified as a callback, it should have the following signature:

```
function ($model, $key, $index, $widget)
```

### $options <span id="property-options"></span>

```php
public array $options = ['class' => 'list-view']
```

The HTML attributes for the container tag of the list view.

The "tag" element specifies the tag name of the container element and defaults to "div".

### $viewParams <span id="property-viewParams"></span>

```php
public array $viewParams = []
```

Additional parameters to be passed to [`$itemView`](/docs/api/yii/widgets/listview/index.md#property-itemView) when it is being rendered.

This property is used only when [`$itemView`](/docs/api/yii/widgets/listview/index.md#property-itemView) is a string representing a view name.

## Method details

### renderItem() <span id="method-renderItem"></span>

```php
public function renderItem(mixed $model, mixed $key, int $index): string
```

Renders a single data model.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$model` | `mixed` | The data model to be rendered |
| `$key` | `mixed` | The key value associated with the data model |
| `$index` | `int` | The zero-based index of the data model in the model array returned by [`$dataProvider`](/docs/api/yii/widgets/baselistview/index.md#property-dataProvider). |

**Returns**

`string`: The rendering result

### renderItems() <span id="method-renderItems"></span>

```php
public function renderItems(): string
```

Renders all data models.

**Returns**

`string`: The rendering result

### renderAfterItem() <span id="method-renderAfterItem"></span>

```php
protected function renderAfterItem(mixed $model, mixed $key, int $index): string|null
```

Calls [`$afterItem`](/docs/api/yii/widgets/listview/index.md#property-afterItem) closure, returns execution result.

If [`$afterItem`](/docs/api/yii/widgets/listview/index.md#property-afterItem) is not a closure, `null` will be returned.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$model` | `mixed` | The data model to be rendered |
| `$key` | `mixed` | The key value associated with the data model |
| `$index` | `int` | The zero-based index of the data model in the model array returned by [`$dataProvider`](/docs/api/yii/widgets/baselistview/index.md#property-dataProvider). |

**Returns**

`string|null`: [`$afterItem`](/docs/api/yii/widgets/listview/index.md#property-afterItem) call result or `null` when [`$afterItem`](/docs/api/yii/widgets/listview/index.md#property-afterItem) is not a closure

**Since**

2.0.11

**See also**

- [`$afterItem`](/docs/api/yii/widgets/listview/index.md#property-afterItem)

### renderBeforeItem() <span id="method-renderBeforeItem"></span>

```php
protected function renderBeforeItem(mixed $model, mixed $key, int $index): string|null
```

Calls [`$beforeItem`](/docs/api/yii/widgets/listview/index.md#property-beforeItem) closure, returns execution result.

If [`$beforeItem`](/docs/api/yii/widgets/listview/index.md#property-beforeItem) is not a closure, `null` will be returned.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$model` | `mixed` | The data model to be rendered |
| `$key` | `mixed` | The key value associated with the data model |
| `$index` | `int` | The zero-based index of the data model in the model array returned by [`$dataProvider`](/docs/api/yii/widgets/baselistview/index.md#property-dataProvider). |

**Returns**

`string|null`: [`$beforeItem`](/docs/api/yii/widgets/listview/index.md#property-beforeItem) call result or `null` when [`$beforeItem`](/docs/api/yii/widgets/listview/index.md#property-beforeItem) is not a closure

**Since**

2.0.11

**See also**

- [`$beforeItem`](/docs/api/yii/widgets/listview/index.md#property-beforeItem)