Try our conversational search powered by Generative AI!

Area: Optimizely CMS
Applies to versions: 10 and higher
Other versions:
ARCHIVED This content is retired and no longer maintained. See the version selector for other versions of this topic.

Using menu providers

Recommended reading 
Note: This documentation is for the preview version of the upcoming release of CMS 12/Commerce 14/Search & Navigation 14. Features included here might not be complete, and might be changed before becoming available in the public release. This documentation is provided for evaluation purposes only.

The building blocks of the navigation are menu providers and menu items. A menu provider provides an enumeration of menu items which are organized in a tree according to their menu path. Optimizely CMS contains a menu provider that looks at [MenuItem] attributes and provides them as menu items.


You can extend the standard menu by implementing a menu provider as an alternative to attributes. The menu provider returns menu items that are correctly localized. To use a menu provider, implement the IMenuProvider interface, decorate it with the [MenuProvider] attribute, and make it part of a registered shell module.

Adding menu items

You can add menu sections and sub-menu items such as menu sections, drop-downs, URLs and pop-up menu items. Each menu item defines a path which determines its location in the menu hierarchy. For example, a URL menu item with path /global/cms/myMenu is placed in the CMS section of the menu (which has the path /global/cms).


  • URL Menu Item are links; a click navigates to specified URL.
  • Popup Menu Item [Obsolete] are links that are opened in a new tab. 
  • Section Menu Item are global menu sections which change the visible menu items.
  • Drop-Down Menu Item are drop-down style menu items designed for the action item area (right-hand side).


    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;

Localizing menu items with a menu provider

A menu provider returns localized menu items.

Permissions with the menu provider

A menu provider can specify AuthorizationPolicy for each menu item, that controls which policy that must apply for the menu item to be available. Another alternative is to defer permission filtering to the menu item by setting the IsAvailable delegate to a method that checks access for the user provided with the HttpContext parameter.

Flow of menu items

Menu items flow from the providers into a hierarchical model, which is rendered into HTML.

Configuring NavigationOptions

The menu can also be extended by configuring NavigationOptions either through code or through appSettings.json as follows:

"EPiServer": {
    "CmsUI": {
        "Navigation": {
            "Items": [
                    "Text": "My section",
                    "MenuItemType": "Section",
                    "MenuPath": "/global/my",
                    "SortIndex": 300
                    "Text": "Edit",
                    "MenuItemType": "Link",
                    "MenuPath": "/global/my/edit",
                    "Url": "/EPiServer/MySecureApp/MyNavigation/Edit",
                    "SortIndex": 100
                    "Text": "Admin",
                    "MenuItemType": "Link",
                    "MenuPath": "/global/my/admin",
                    "Url": "/EPiServer/MySecureApp/MyNavigation/Admin",
                    "SortIndex": 200
Do you find this information helpful? Please log in to provide feedback.

Last updated: Jul 02, 2021

Recommended reading