---
title: Add and configure menu items
slug: cms-12/docs/adding-and-configuring-menu-items
docTags: 
createdAt: 2026-08-10T15:55:59.000Z
---

## MenuItem attribute

Use `MenuItem` on MVC controllers. `MenuItem` adds links to the top menu (and requires the module to be registered; see [Configure Shell modules](docId\:prd5_cCC_c8HF0jc0-5vQ). The required `menuPath` parameter is a logical path of the menu element in the menu. The `Url` parameter can optionally be added to specify the linked URL to the interface. By default, the URL is set to the registered shell route for the module (`/EPiServer/{ShellModule}/{controller}/{action}` for protected modules and `/modules/{ShellModule}/{controller}/{action}` for public modules).

The following example adds a menu item to the top menu bar with the text **Start**, and the URL is inferred from the registered route for the shell module:

```csharp
public class DashboardController : Controller {
  [MenuItem("/global/dashboard", Text = "Start")]
  public ActionResult Index() {
  }
}
```

When you have added menu items, you need to implement the page to include CMS's styling for Shell and also render the menu so you can navigate back.

The key function to render a menu is `@Html.CreatePlatformNavigationMenu()`.

Note that the calls to `Html.ShellInitializationScript()` might still be needed depending on what content you are showing in addition to the navigation menu. It is not necessary for the navigation menu itself.

In addition to `Html.CreatePlatformNavigationMenu`, you must also wrap content below the menu in an element decorated by using this HTML helper `html.ApplyPlatformNavigation()`.

:::hint{type="info"}
**Note**
The Platform Navigation font sizing uses REM and expects the root element to have size 16px (browser default). Some style frameworks, such as Bootstrap 3, override the root font size while others, like Bootstrap 4, do not.
:::

To adapt the example above to work with CMS versions 11.21 and higher, you need to start using `CreatePlatformNavigationMenu()` and `ApplyPlatformNavigation()`.

:::hint{type="info"}
**Note**
You no longer need `@Html.Raw(ClientResources.RenderResources("Navigation"))` nor `@Html.Raw(Html.ShellInitializationScript())`.
:::

```csharp
@using EPiServer.Framework.Web.Resources
@using EPiServer.Shell.Navigation

<!DOCTYPE html>
<html>
  <head>
    <title>@ViewBag.Title</title>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    
    <!-- Shell -->
    @ClientResources.RenderResources("ShellCore")
    
    <!-- LightTheme -->
    @ClientResources.RenderResources("ShellCoreLightTheme")
  </head>
  <body>
    @Html.CreatePlatformNavigationMenu()
    <div @Html.ApplyPlatformNavigation()>
        @RenderBody()
    </div>
  </body>
</html>
```

### Localize menu items with the MenuItem attribute

You can localize menu items by specifying `TextResourceKey`. By default, is the key resolved against `LocalizationService`. Alternatively attribute `ResourceType` can be specified that then should be a class with a static property named `TextResourceKey` that returns the localized text.

Example:

```csharp
[MenuItem("/global/dashboard", 
  TextResourceKey = "Start", 
  ResourceType = typeof(MenuResources))]
```

### Organize menu items

The menu path is used to organize menu items in a tree structure. Menu items in the top menu are in the `/global` bucket. The next segment is the name of the menu section, for example, `/global/cms`. The last segment represents the actual user interface, for example, `/global/cms/edit`.

### Permissions with the MenuItem attribute

By default, a security policy is applied to controllers for a shell module. You can configure the policy to use through `_authorizationPolicy_` in [module.config](docId\:RZVSXXKVRj26ep5OsAUB-). The availability of the menu item is then evaluated through the policy. You can apply the [AuthorizeAttribute](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authorization.authorizeattribute?view=aspnetcore-5.0) to specify a custom authorization to complement the default policy that applies to the module. However, if there is a policy for the shell module, then that policy is also evaluated for the request.

```csharp
public class DashboardController : Controller {
  [MenuItem("/global/dashboard")]
  [Authorize(Roles = "SomeGroup")]
  public ActionResult Index() {
  }
}
```

## Add menu item examples

The following examples show how to add menu items.

### Global menu button

```csharp
namespace Alloy.Business {
  public class EpiServerWorldGlobalMenuItem: Controller {
    [MenuItem(MenuPaths.Global + "/globalLink",
      SortIndex = SortIndex.First - 10,
      Text = "Optimizely world",
      Url = "https://world.episerver.com/cms/")]
    public ActionResult Index(string viewName) {
      return View();
    }
  }
}
```

### Extend the CMS menu section

```csharp
namespace Alloy.Business {
  [MenuProvider]
  public class CmsMenuProvider: IMenuProvider {
    private readonly ModuleTable _modules;

    public CmsMenuProvider(ModuleTable modules) {
      _modules = modules;
    }

    public IEnumerable<MenuItem> GetMenuItems() {
      var menuItems = new List<MenuItem>();
      menuItems.Add(new UrlMenuItem("Another link to Admin",
        MenuPaths.Global + "/cms" + "/cmsMenuItem",
        Path.Combine(_modules.FindModule("EPiServer.CMS.UI.Admin").ResourceBasePath, "default")) {
        SortIndex = SortIndex.First + 25,
          AuthorizationPolicy = CmsPolicyNames.CmsAdmin
      });

      return menuItems;
    }
  }
}
```

### Add a second-level menu

The following example adds a second-level menu to the existing admin menu.

```csharp
public class ExtendedAdminController : Controller {
  [MenuItem("/global/cms/admin/extension", Text = "Admin Extension", SortIndex = 60)]
  public IActionResult Index() {
    return View();
  }
}
```

### Global menu section

While the example below works, you should not use the main navigation for external links. A better example for external links could be the following example (*Extending the User Settings menu using menu provider*).

```csharp
using System.Collections.Generic;
using EPiServer.Security;
using EPiServer.Shell.Navigation;

namespace Alloy.Business {
  [MenuProvider]
  public class GlbalSectionMenuProvider: IMenuProvider {
    const string MainMenuPath = MenuPaths.Global + "/customSection";

    public IEnumerable<MenuItem> GetMenuItems() {
      var menuItems = new List<MenuItem>();

      menuItems.Add(new SectionMenuItem("Optimizely Forum", MainMenuPath) {
        SortIndex = SortIndex.Last + 10
      });

      menuItems.Add(new UrlMenuItem("CMS", MainMenuPath + "/item1",
        "https://world.episerver.com/forum/developer-forum/-Optimizely-75-CMS/") {
        SortIndex = 1,
      });

      menuItems.Add(new UrlMenuItem("Commerce", MainMenuPath + "/item2",
        "https://world.episerver.com/forum/developer-forum/Optimizely-Commerce/") {
        SortIndex = 2,
      });

      menuItems.Add(new UrlMenuItem("Forms", MainMenuPath + "/item3",
        "https://world.episerver.com/forum/developer-forum/episerver-forms/") {
        SortIndex = 3,
      });

      return menuItems;
    }
  }
}
```

### Use MenuProvider to extend the User Settings menu

```csharp
using System.Collections.Generic;
using EPiServer.Shell.Navigation;

namespace Alloy.Business {
  [MenuProvider]
  public class UserSettingsMenuProvider: IMenuProvider {
    public IEnumerable<MenuItem> GetMenuItems() {
      var menuItems = new List<MenuItem>();
      var item = new UrlMenuItem("Documentation",
        MenuPaths.User + "/episerver2", "https://world.episerver.com/documentation/") {
        SortIndex = SortIndex.Last + 10
      };
      menuItems.Add(item);
      return menuItems;
    }
  }
}
```

### Extend the User Settings menu using controller action

```csharp
using EPiServer.Shell.Navigation;

namespace Alloy.Business {
  /// <summary>
  ///  Menu item under User Settings menu (menu added using controller action)
  /// </summary>
  /// <returns></returns>
  public class EpiServerWorldMenuItem: Controller {
    [MenuItem(MenuPaths.UserSettings, SortIndex = SortIndex.First - 10, Text = "About Optimizely",
      Url = "https://www.episerver.com/about/company/overview/")]
    public ActionResult Index(string viewName) {
      return View();
    }
  }
}
```

### Drop-down menu with items

```csharp
using System.Collections.Generic;
using EPiServer.Shell.Navigation;

namespace Alloy.Business {
  [MenuProvider]
  public class DropdownMenuProvider: IMenuProvider {
    const string DropdownMenuPath = MenuPaths.Global + "/customDropdownMenu";

    public IEnumerable<MenuItem> GetMenuItems() {
      var menuItems = new List<MenuItem>();

      var userMenu = new DropDownMenuItem("Optimizely blogs", DropdownMenuPath) {
        SortIndex = SortIndex.Last - 20,
          Alignment = MenuItemAlignment.Right
      };
      menuItems.Add(userMenu);

      menuItems.Add(new UrlMenuItem("CMS", DropdownMenuPath + "/item1",
        "https://world.episerver.com/blogs/?type=cmsblog&page=1") {
        SortIndex = 1,
      });

      menuItems.Add(new UrlMenuItem("Commerce", DropdownMenuPath + "/item2",
        "https://world.episerver.com/blogs/?type=commerceblog&page=1") {
        SortIndex = 2,
      });

      menuItems.Add(new UrlMenuItem("Find", DropdownMenuPath + "/item3",
        "https://world.episerver.com/blogs/?type=findblog&page=1") {
        SortIndex = 3,
      });

      return menuItems;
    }
  }
}
```