# Menu

> Menu displays a multi-level menu using nested HTML lists.

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

| class | `yii\widgets\Menu` |
| --- | --- |
| Extends | [`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/Menu.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/widgets/Menu.php#L51) |

Menu displays a multi-level menu using nested HTML lists.

The main property of Menu is [`$items`](/docs/api/yii/widgets/menu/index.md#property-items), which specifies the possible items in the menu.
A menu item can contain sub-items which specify the sub-menu under that menu item.

Menu checks the current route and request parameters to toggle certain menu items
with active state.

Note that Menu only renders the HTML tags about the menu. It does not do any styling.
You are responsible to provide CSS styles to make it look like a real menu.

The following example shows how to use Menu:

```
echo Menu::widget([
    'items' => [
        // Important: you need to specify url as 'controller/action',
        // not just as 'controller' even if default action is used.
        ['label' => 'Home', 'url' => ['site/index']],
        // 'Products' menu item will be selected as long as the route is 'product/index'
        ['label' => 'Products', 'url' => ['product/index'], 'items' => [
            ['label' => 'New Arrivals', 'url' => ['product/index', 'tag' => 'new']],
            ['label' => 'Most Popular', 'url' => ['product/index', 'tag' => 'popular']],
        ]],
        ['label' => 'Login', 'url' => ['site/login'], 'visible' => Yii::$app->user->isGuest],
    ],
]);
```

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-activateItems"></span>`$activateItems` | `bool` | Whether to automatically activate items according to whether their route setting matches the currently requested route. Default: `true`. | `Menu` |
| [`$activateParents`](#property-activateParents) | `bool` | Whether to activate parent menu items when one of the corresponding child menu items is active. Default: `false`. | `Menu` |
| <span id="property-activeCssClass"></span>`$activeCssClass` | `string` | The CSS class to be appended to the active menu item. Default: `'active'`. | `Menu` |
| <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) |
| <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-encodeLabels"></span>`$encodeLabels` | `bool` | Whether the labels for menu items should be HTML-encoded. Default: `true`. | `Menu` |
| [`$firstItemCssClass`](#property-firstItemCssClass) | `string\|null` | The CSS class that will be assigned to the first item in the main menu or each submenu. Default: `null`. | `Menu` |
| [`$hideEmptyItems`](#property-hideEmptyItems) | `bool` | Whether to hide empty menu items. Default: `true`. | `Menu` |
| <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` | List of HTML attributes shared by all menu [`$items`](/docs/api/yii/widgets/menu/index.md#property-items). Default: `[]`. | `Menu` |
| [`$items`](#property-items) | `array` | List of menu items. Default: `[]`. | `Menu` |
| [`$labelTemplate`](#property-labelTemplate) | `string` | The template used to render the body of a menu which is NOT a link. Default: `'{label}'`. | `Menu` |
| [`$lastItemCssClass`](#property-lastItemCssClass) | `string\|null` | The CSS class that will be assigned to the last item in the main menu or each submenu. Default: `null`. | `Menu` |
| [`$linkTemplate`](#property-linkTemplate) | `string` | The template used to render the body of a menu which is a link. Default: `'<a href="{url}">{label}</a>'`. | `Menu` |
| [`$options`](#property-options) | `array` | The HTML attributes for the menu's container tag. Default: `[]`. | `Menu` |
| [`$params`](#property-params) | `array\|null` | The parameters used to determine if a menu item is active or not. Default: `null`. | `Menu` |
| [`$route`](#property-route) | `string\|null` | The route used to determine if a menu item is active or not. Default: `null`. | `Menu` |
| [`$submenuTemplate`](#property-submenuTemplate) | `string` | The template used to render a list of sub-menus. Default: `"\n<ul>\n{items}\n</ul>\n"`. | `Menu` |
| <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) |
| <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/base/widget/index.md#method-init) | Initializes the object. | [`yii\base\Widget`](/docs/api/yii/base/widget/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-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) |
| [`run()`](#method-run) | Renders the menu. | `Menu` |
| <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) |
| [`isItemActive()`](#method-isItemActive) protected | Checks whether a menu item is active. | `Menu` |
| [`normalizeItems()`](#method-normalizeItems) protected | Normalizes the [`$items`](/docs/api/yii/widgets/menu/index.md#property-items) property to remove invisible items and activate certain items. | `Menu` |
| [`renderItem()`](#method-renderItem) protected | Renders the content of a menu item. | `Menu` |
| [`renderItems()`](#method-renderItems) protected | Recursively renders the menu items (without the container tag). | `Menu` |

## 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

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

```php
public bool $activateParents = false
```

Whether to activate parent menu items when one of the corresponding child menu items is active.

The activated parent menu items will also have its CSS classes appended with [`$activeCssClass`](/docs/api/yii/widgets/menu/index.md#property-activeCssClass).

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

```php
public string|null $firstItemCssClass = null
```

The CSS class that will be assigned to the first item in the main menu or each submenu.

Defaults to null, meaning no such CSS class will be assigned.

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

```php
public bool $hideEmptyItems = true
```

Whether to hide empty menu items.

An empty menu item is one whose `url` option is not
set and which has no visible child menu items.

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

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

List of HTML attributes shared by all menu [`$items`](/docs/api/yii/widgets/menu/index.md#property-items).

If any individual menu item
specifies its `options`, it will be merged with this property before being used to generate the HTML
attributes for the menu item tag. The following special options are recognized:

- tag: string, defaults to "li", the tag name of the item container tags.
  Set to false to disable container tag.
  See also [`Html::tag()`](/docs/api/yii/helpers/basehtml/index.md#method-tag).

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

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

List of menu items.

Each menu item should be an array of the following structure:

- label: string, optional, specifies the menu item label. When [`$encodeLabels`](/docs/api/yii/widgets/menu/index.md#property-encodeLabels) is true, the label
  will be HTML-encoded. If the label is not specified, an empty string will be used.
- encode: boolean, optional, whether this item`s label should be HTML-encoded. This param will override
  global [`$encodeLabels`](/docs/api/yii/widgets/menu/index.md#property-encodeLabels) param.
- url: string or array, optional, specifies the URL of the menu item. It will be processed by [`Url::to()`](/docs/api/yii/helpers/baseurl/index.md#method-to).
  When this is set, the actual menu item content will be generated using [`$linkTemplate`](/docs/api/yii/widgets/menu/index.md#property-linkTemplate);
  otherwise, [`$labelTemplate`](/docs/api/yii/widgets/menu/index.md#property-labelTemplate) will be used.
- visible: boolean, optional, whether this menu item is visible. Defaults to true.
- items: array, optional, specifies the sub-menu items. Its format is the same as the parent items.
- active: boolean or Closure, optional, whether this menu item is in active state (currently selected).
  When using a closure, its signature should be `function ($item, $hasActiveChild, $isItemActive, $widget)`.
  Closure must return `true` if item should be marked as `active`, otherwise - `false`.
  If a menu item is active, its CSS class will be appended with [`$activeCssClass`](/docs/api/yii/widgets/menu/index.md#property-activeCssClass).
  If this option is not set, the menu item will be set active automatically when the current request
  is triggered by `url`. For more details, please refer to [`isItemActive()`](/docs/api/yii/widgets/menu/index.md#method-isItemActive).
- template: string, optional, the template used to render the content of this menu item.
  The token `{url}` will be replaced by the URL associated with this menu item,
  and the token `{label}` will be replaced by the label of the menu item.
  If this option is not set, [`$linkTemplate`](/docs/api/yii/widgets/menu/index.md#property-linkTemplate) or [`$labelTemplate`](/docs/api/yii/widgets/menu/index.md#property-labelTemplate) will be used instead.
- submenuTemplate: string, optional, the template used to render the list of sub-menus.
  The token `{items}` will be replaced with the rendered sub-menu items.
  If this option is not set, [`$submenuTemplate`](/docs/api/yii/widgets/menu/index.md#property-submenuTemplate) will be used instead.
- options: array, optional, the HTML attributes for the menu container tag.

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

```php
public string $labelTemplate = '{label}'
```

The template used to render the body of a menu which is NOT a link.

In this template, the token `{label}` will be replaced with the label of the menu item.
This property will be overridden by the `template` option set in individual menu items via [`$items`](/docs/api/yii/widgets/menu/index.md#property-items).

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

```php
public string|null $lastItemCssClass = null
```

The CSS class that will be assigned to the last item in the main menu or each submenu.

Defaults to null, meaning no such CSS class will be assigned.

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

```php
public string $linkTemplate = '<a href="{url}">{label}</a>'
```

The template used to render the body of a menu which is a link.

In this template, the token `{url}` will be replaced with the corresponding link URL;
while `{label}` will be replaced with the link text.
This property will be overridden by the `template` option set in individual menu items via [`$items`](/docs/api/yii/widgets/menu/index.md#property-items).

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

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

The HTML attributes for the menu's container tag.

The following special options are recognized:

- tag: string, defaults to "ul", the tag name of the item container tags. Set to false to disable container tag.
  See also [`Html::tag()`](/docs/api/yii/helpers/basehtml/index.md#method-tag).

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

```php
public array|null $params = null
```

The parameters used to determine if a menu item is active or not.

If not set, it will use `$_GET`.

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

```php
public string|null $route = null
```

The route used to determine if a menu item is active or not.

If not set, it will use the route of the current request.

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

```php
public string $submenuTemplate = "\n<ul>\n{items}\n</ul>\n"
```

The template used to render a list of sub-menus.

In this template, the token `{items}` will be replaced with the rendered sub-menu items.

## Method details

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

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

Renders the menu.

**Returns**

`mixed`

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

```php
protected function isItemActive(array $item): bool
```

Checks whether a menu item is active.

This is done by checking if [`$route`](/docs/api/yii/widgets/menu/index.md#property-route) and [`$params`](/docs/api/yii/widgets/menu/index.md#property-params) match that specified in the `url` option of the menu item.
When the `url` option of a menu item is specified in terms of an array, its first element is treated
as the route for the item and the rest of the elements are the associated parameters.
Only when its route and parameters match [`$route`](/docs/api/yii/widgets/menu/index.md#property-route) and [`$params`](/docs/api/yii/widgets/menu/index.md#property-params), respectively, will a menu item
be considered active.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$item` | `array` | The menu item to be checked |

**Returns**

`bool`: Whether the menu item is active

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

```php
protected function normalizeItems(array $items, bool &$active): array
```

Normalizes the [`$items`](/docs/api/yii/widgets/menu/index.md#property-items) property to remove invisible items and activate certain items.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$items` | `array` | The items to be normalized. |
| `$active` | `bool` | Whether there is an active child menu item. |

**Returns**

`array`: The normalized menu items

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

```php
protected function renderItem(array $item): string
```

Renders the content of a menu item.

Note that the container and the sub-menus are not rendered here.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$item` | `array` | The menu item to be rendered. Please refer to [`$items`](/docs/api/yii/widgets/menu/index.md#property-items) to see what data might be in the item. |

**Returns**

`string`: The rendering result

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

```php
protected function renderItems(array $items): string
```

Recursively renders the menu items (without the container tag).

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$items` | `array` | The menu items to be rendered recursively |

**Returns**

`string`: The rendering result