# Widget

> Widget is the base class for widgets.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [base](/docs/api/yii/base/index.md) › Widget

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

16 subclasses:

- [`yii\console\widgets\Table`](/docs/api/yii/console/widgets/table/index.md)
- [`yii\widgets\ActiveForm`](/docs/api/yii/widgets/activeform/index.md)
- [`yii\widgets\BaseListView`](/docs/api/yii/widgets/baselistview/index.md)
- [`yii\widgets\Block`](/docs/api/yii/widgets/block/index.md)
- [`yii\widgets\Breadcrumbs`](/docs/api/yii/widgets/breadcrumbs/index.md)
- [`yii\widgets\ContentDecorator`](/docs/api/yii/widgets/contentdecorator/index.md)
- [`yii\widgets\DetailView`](/docs/api/yii/widgets/detailview/index.md)
- [`yii\widgets\FragmentCache`](/docs/api/yii/widgets/fragmentcache/index.md)
- [`yii\widgets\InputWidget`](/docs/api/yii/widgets/inputwidget/index.md)
- [`yii\widgets\LinkPager`](/docs/api/yii/widgets/linkpager/index.md)
- [`yii\widgets\LinkSorter`](/docs/api/yii/widgets/linksorter/index.md)
- [`yii\widgets\Menu`](/docs/api/yii/widgets/menu/index.md)
- [`yii\widgets\Pjax`](/docs/api/yii/widgets/pjax/index.md)
- [`yii\widgets\Spaceless`](/docs/api/yii/widgets/spaceless/index.md)
- [`yii2\extensions\bootstrap6\Widget`](/docs/extensions/bootstrap6/reference/widget/index.md)
- [`yii\debug\widgets\FilterBanner`](/docs/extensions/debug/reference/widgets/filterbanner/index.md)

Widget is the base class for widgets.

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

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-autoIdPrefix"></span>`$autoIdPrefix` static | `string` | The prefix to the automatically generated widget IDs. Default: `'w'`. | `Widget` |
| <span id="property-behaviors"></span>[`$behaviors`](/docs/api/yii/base/component/index.md#property-behaviors) read-only | `array<`[`Behavior`](/docs/api/yii/base/behavior/index.md)`<static>>` | List of behaviors attached to this component. | [`Component`](/docs/api/yii/base/component/index.md) |
| <span id="property-id"></span>`$id` | `string` | Id of the widget. | `Widget` |
| <span id="property-view"></span>`$view` | [`yii\web\View`](/docs/api/yii/web/view/index.md) | The view object that can be used to render views or view files. | `Widget` |
| <span id="property-viewPath"></span>`$viewPath` read-only | `string` | The directory containing the view files for this widget. | `Widget` |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-__construct"></span>[`__construct()`](/docs/api/yii/base/baseobject/index.md#method-__construct) | Constructor. | [`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. | [`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. | [`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. | [`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. | [`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. | [`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. | [`Component`](/docs/api/yii/base/component/index.md) |
| [`afterRun()`](#method-afterRun) | This method is invoked right after a widget is executed. | `Widget` |
| <span id="method-attachBehavior"></span>[`attachBehavior()`](/docs/api/yii/base/component/index.md#method-attachBehavior) | Attaches a behavior to this component. | [`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. | [`Component`](/docs/api/yii/base/component/index.md) |
| [`beforeRun()`](#method-beforeRun) | This method is invoked right before the widget is executed. | `Widget` |
| [`begin()`](#method-begin) static | Begins a widget. | `Widget` |
| <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. | [`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. | [`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. | [`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. | [`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. | [`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. | [`Component`](/docs/api/yii/base/component/index.md) |
| [`end()`](#method-end) static | Ends a widget. | `Widget` |
| <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. | [`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. | [`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. | [`Component`](/docs/api/yii/base/component/index.md) |
| [`getId()`](#method-getId) | Returns the ID of the widget. | `Widget` |
| [`getView()`](#method-getView) | Returns the view object that can be used to render views or view files. | `Widget` |
| [`getViewPath()`](#method-getViewPath) | Returns the directory containing the view files for this widget. | `Widget` |
| <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. | [`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. | [`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. | [`Component`](/docs/api/yii/base/component/index.md) |
| [`init()`](#method-init) | Initializes the object. | `Widget` |
| <span id="method-off"></span>[`off()`](/docs/api/yii/base/component/index.md#method-off) | Detaches an existing event handler from this component. | [`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. | [`Component`](/docs/api/yii/base/component/index.md) |
| [`render()`](#method-render) | Renders a view. | `Widget` |
| [`renderFile()`](#method-renderFile) | Renders a view file. | `Widget` |
| [`run()`](#method-run) | Executes the widget. | `Widget` |
| [`setId()`](#method-setId) | Sets the ID of the widget. | `Widget` |
| [`setView()`](#method-setView) | Sets the view object to be used by this widget. | `Widget` |
| <span id="method-trigger"></span>[`trigger()`](/docs/api/yii/base/component/index.md#method-trigger) | Triggers an event. | [`Component`](/docs/api/yii/base/component/index.md) |
| [`widget()`](#method-widget) static | Creates a widget instance and runs it. | `Widget` |

## Events

| Event | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="event-EVENT_INIT"></span>`EVENT_INIT` | [`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. | `Widget` |
| <span id="event-EVENT_BEFORE_RUN"></span>`EVENT_BEFORE_RUN` | [`WidgetEvent`](/docs/api/yii/base/widgetevent/index.md) | An event raised right before executing a widget. Event name: `'beforeRun'`. Available since 2.0.11. | `Widget` |
| <span id="event-EVENT_AFTER_RUN"></span>`EVENT_AFTER_RUN` | [`WidgetEvent`](/docs/api/yii/base/widgetevent/index.md) | An event raised right after executing a widget. Event name: `'afterRun'`. Available since 2.0.11. | `Widget` |

## Method details

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

```php
public function afterRun(mixed $result): mixed
```

This method is invoked right after a widget is executed.

The method will trigger the [`EVENT_AFTER_RUN`](/docs/api/yii/base/widget/index.md#event-EVENT_AFTER_RUN) event. The return value of the method
will be used as the widget return value.

If you override this method, your code should look like the following:

```
public function afterRun($result)
{
    $result = parent::afterRun($result);
    // your custom code here
    return $result;
}
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$result` | `mixed` | The widget return result. |

**Returns**

`mixed`: The processed widget result.

**Since**

2.0.11

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

```php
public function beforeRun(): bool
```

This method is invoked right before the widget is executed.

The method will trigger the [`EVENT_BEFORE_RUN`](/docs/api/yii/base/widget/index.md#event-EVENT_BEFORE_RUN) event. The return value of the method
will determine whether the widget should continue to run.

When overriding this method, make sure you call the parent implementation like the following:

```
public function beforeRun()
{
    if (!parent::beforeRun()) {
        return false;
    }

    // your custom code here

    return true; // or false to not run the widget
}
```

**Returns**

`bool`: Whether the widget should continue to be executed.

**Since**

2.0.11

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

```php
public static function begin(array $config = []): static
```

Begins a widget.

This method creates an instance of the calling class. It will apply the configuration
to the created instance. A matching [`end()`](/docs/api/yii/base/widget/index.md#method-end) call should be called later.
As some widgets may use output buffering, the [`end()`](/docs/api/yii/base/widget/index.md#method-end) call should be made in the same view
to avoid breaking the nesting of output buffers.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$config` | `array` | Name-value pairs that will be used to initialize the object properties |

**Returns**

`static`: The newly created widget instance

**See also**

- [`end()`](/docs/api/yii/base/widget/index.md#method-end)

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

```php
public static function end(): static
```

Ends a widget.

Note that the rendering result of the widget is directly echoed out.

**Returns**

`static`: The widget instance that is ended.

**Throws**

- [`InvalidCallException`](/docs/api/yii/base/invalidcallexception/index.md): if [`begin()`](/docs/api/yii/base/widget/index.md#method-begin) and [`end()`](/docs/api/yii/base/widget/index.md#method-end) calls are not properly nested

**See also**

- [`begin()`](/docs/api/yii/base/widget/index.md#method-begin)

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

```php
public function getId(bool $autoGenerate = true): string|null
```

Returns the ID of the widget.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$autoGenerate` | `bool` | Whether to generate an ID if it is not set previously |

**Returns**

`string|null`: ID of the widget.

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

```php
public function getView(): yii\web\View
```

Returns the view object that can be used to render views or view files.

The [`render()`](/docs/api/yii/base/widget/index.md#method-render) and [`renderFile()`](/docs/api/yii/base/widget/index.md#method-renderFile) methods will use
this view object to implement the actual view rendering.
If not set, it will default to the "view" application component.

**Returns**

[`yii\web\View`](/docs/api/yii/web/view/index.md): The view object that can be used to render views or view files.

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

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

Returns the directory containing the view files for this widget.

The default implementation returns the 'views' subdirectory under the directory containing the widget class file.

**Returns**

`string`: The directory containing the view files for this widget.

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

```php
public function init(): mixed
```

Initializes the object.

This method is called at the end of the constructor.
The default implementation will trigger an [`EVENT_INIT`](/docs/api/yii/base/widget/index.md#event-EVENT_INIT) event.

**Returns**

`mixed`

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

```php
public function render(string $view, array $params = []): string
```

Renders a view.

The view to be rendered can be specified in one of the following formats:

- [path alias](/docs/guide/concept-aliases/index.md) (e.g. "@app/views/site/index");
- absolute path within application (e.g. "//site/index"): the view name starts with double slashes.
  The actual view file will be looked for under the [view path](/docs/api/yii/base/module/index.md#property-viewPath) of the application.
- absolute path within module (e.g. "/site/index"): the view name starts with a single slash.
  The actual view file will be looked for under the [view path](/docs/api/yii/base/module/index.md#property-viewPath) of the currently
  active module.
- relative path (e.g. "index"): the actual view file will be looked for under [`$viewPath`](/docs/api/yii/base/widget/index.md#property-viewPath).

If the view name does not contain a file extension, it will use the default one `.php`.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$view` | `string` | The view name. |
| `$params` | `array` | The parameters (name-value pairs) that should be made available in the view. |

**Returns**

`string`: The rendering result.

**Throws**

- [`InvalidArgumentException`](/docs/api/yii/base/invalidargumentexception/index.md): if the view file does not exist.

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

```php
public function renderFile(string $file, array $params = []): string
```

Renders a view file.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$file` | `string` | The view file to be rendered. This can be either a file path or a [path alias](/docs/guide/concept-aliases/index.md). |
| `$params` | `array` | The parameters (name-value pairs) that should be made available in the view. |

**Returns**

`string`: The rendering result.

**Throws**

- [`InvalidArgumentException`](/docs/api/yii/base/invalidargumentexception/index.md): if the view file does not exist.

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

```php
public function run(): string|void
```

Executes the widget.

**Returns**

`string|void`: The rendering result may be directly "echoed" or returned as a string

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

```php
public function setId(string $value): mixed
```

Sets the ID of the widget.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `string` | Id of the widget. |

**Returns**

`mixed`

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

```php
public function setView(yii\web\View $view): mixed
```

Sets the view object to be used by this widget.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$view` | [`yii\web\View`](/docs/api/yii/web/view/index.md) | The view object that can be used to render views or view files. |

**Returns**

`mixed`

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

```php
public static function widget(array $config = []): string
```

Creates a widget instance and runs it.

The widget rendering result is returned by this method.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$config` | `array` | Name-value pairs that will be used to initialize the object properties |

**Returns**

`string`: The rendering result of the widget.

**Throws**

- [`Throwable`](https://www.php.net/manual/en/class.throwable.php)