# BootstrapWidgetTrait

> Provides Bootstrap plugin registration, client options, and client events for widgets.

[API reference](/docs/api/index.md) › [Bootstrap 6](/docs/extensions/bootstrap6/reference/index.md) › BootstrapWidgetTrait

| trait | `yii2\extensions\bootstrap6\BootstrapWidgetTrait` |
| --- | --- |
| Source | [`src/BootstrapWidgetTrait.php`](https://github.com/yii2-extensions/bootstrap6/blob/main/src/BootstrapWidgetTrait.php#L27) |

Used by 2 types:

- [`InputWidget`](/docs/extensions/bootstrap6/reference/inputwidget/index.md)
- [`Widget`](/docs/extensions/bootstrap6/reference/widget/index.md)

Provides Bootstrap plugin registration, client options, and client events for widgets.

The using class must declare a public `$options` array; the trait fills `$options['id']` when it is not set.
Plugins initialize through a dynamic `import()` of the same module URL that [`BootstrapPluginAsset`](/docs/extensions/bootstrap6/reference/asset/bootstrappluginasset/index.md) registers,
so the browser evaluates the bundle once and no global is required.

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| [`$clientEvents`](#property-clientEvents) | `array<string,` [`yii\web\JsExpression`](/docs/api/yii/web/jsexpression/index.md)`\|string>` | Event handlers attached to the widget element, as event name => JavaScript handler source. Default: `[]`. | `BootstrapWidgetTrait` |
| [`$clientOptions`](#property-clientOptions) | `array<string, mixed>\|false` | Options passed to the plugin constructor, or `false` to skip the JavaScript initialization. Default: `[]`. | `BootstrapWidgetTrait` |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`init()`](#method-init) | Initializes the widget and assigns an `id` to `$options` when it is not set. | `BootstrapWidgetTrait` |
| [`pluginInitialization()`](#method-pluginInitialization) protected | Returns the JavaScript that initializes a plugin with its normalized constructor options. | `BootstrapWidgetTrait` |
| [`registerClientEvents()`](#method-registerClientEvents) protected | Registers the JavaScript event handlers listed in [`$clientEvents`](/docs/extensions/bootstrap6/reference/bootstrapwidgettrait/index.md#property-clientEvents) at [`View::POS_END`](/docs/api/yii/web/view/index.md#const-POS_END). | `BootstrapWidgetTrait` |
| [`registerPlugin()`](#method-registerPlugin) protected | Registers the plugin asset, the plugin initialization when needed, and the [`$clientEvents`](/docs/extensions/bootstrap6/reference/bootstrapwidgettrait/index.md#property-clientEvents). | `BootstrapWidgetTrait` |

## Property details

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

```php
public array<string, yii\web\JsExpression|string> $clientEvents = []
```

Event handlers attached to the widget element, as event name => JavaScript handler source.

For example, `['shown.bs.toast' => 'function (event) { ... }']`.

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

```php
public array<string, mixed>|false $clientOptions = []
```

Options passed to the plugin constructor, or `false` to skip the JavaScript initialization.

Enum cases at any depth are encoded as their value (backed) or name (pure), and [`Stringable`](https://www.php.net/manual/en/class.stringable.php) values as their
`string`; [`JsExpression`](/docs/api/yii/web/jsexpression/index.md) values are emitted as raw JavaScript.

## Method details

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

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

Initializes the widget and assigns an `id` to `$options` when it is not set.

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

```php
protected function pluginInitialization(string $name, string $element, string $options): string
```

Returns the JavaScript that initializes a plugin with its normalized constructor options.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$name` | `string` | Plugin class exported by the bundle. |
| `$element` | `string` | JavaScript expression selecting the plugin element. |
| `$options` | `string` | JSON-encoded constructor options. |

**Returns**

`string`

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

```php
protected function registerClientEvents(): void
```

Registers the JavaScript event handlers listed in [`$clientEvents`](/docs/extensions/bootstrap6/reference/bootstrapwidgettrait/index.md#property-clientEvents) at [`View::POS_END`](/docs/api/yii/web/view/index.md#const-POS_END).

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

```php
protected function registerPlugin(string $name, bool $always = false): void
```

Registers the plugin asset, the plugin initialization when needed, and the [`$clientEvents`](/docs/extensions/bootstrap6/reference/bootstrapwidgettrait/index.md#property-clientEvents).

The initialization is emitted when [`$clientOptions`](/docs/extensions/bootstrap6/reference/bootstrapwidgettrait/index.md#property-clientOptions) is a non-empty array, or when `$always` is `true` and
[`$clientOptions`](/docs/extensions/bootstrap6/reference/bootstrapwidgettrait/index.md#property-clientOptions) is not `false`.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$name` | `string` | Plugin class exported by the bundle, for example `Toast`. |
| `$always` | `bool` | Whether to initialize the plugin even when [`$clientOptions`](/docs/extensions/bootstrap6/reference/bootstrapwidgettrait/index.md#property-clientOptions) is empty. |

**Throws**

- [`yii\base\InvalidArgumentException`](/docs/api/yii/base/invalidargumentexception/index.md): if the bundle does not export the plugin.