Menu Widgets

This article describes common principles of working with menu widgets.

DevExtreme includes the following menu widgets.

Common Tasks

This section describes tasks common for menu widgets. These tasks include data binding, appearance customization, item selection and events handling.

Data Binding

Menu widgets, like all other collection container widgets, include a dataSource property. This property takes a DataSource instance, an object that provides the required data as an array for the Menu widget from any storage (from a local one to a web service). This is a stateful object that stores sorting, grouping, and filtering options, as well as information on how to transform data; these options are applied to the data array every time data is loaded. DataSource objects are provided for simple scenarios such as data stored locally, or more complex situations like data provided by a web service.

HTML
<div data-bind="dxMenu:{ dataSource: menuItems }"></div>
JavaScript
var menuItems = [
    {
        text: "Item1",
        icon: "icon1",
        items: [
            { text: "Item11" },
            { text: "Item12" },
            { text: "Item13" }
        ]
    },
    {
        text: "Item2",
        icon: "icon2",
        items: [
            { text: "Item21" },
            { text: "Item22" },
            { text: "Item23" }
        ]
    }
];

For detailed information on working with the Data Source object, refer to the Data Layer and Data Source Examples documentation sections.

Appearance

Menu items are displayed using templates. In a common case, you can use a default item template. This template displays text with an icon based on the text and icon item data source fields. You can define a custom item template. It can also be based on specific fields of an item data source. To learn how to set custom templates, refer to the Customize Widget Item Appearance article.

Item Selection

Menu widgets allow end-users to select items.

Only a single item at a time can be selected within a submenu.

You can pre-select a particular menu item. To do this, set that item's selected data source field to true.

JavaScript
var menuItems = [
    {text: "item1"},
    {text: "item2", selected: true}
];

To access the currently selected item, use the widget's selectedItem option, which just holds the selected item and does not change the selection.

You can prohibit an end-user from selecting specific items. To do this, set that items' selected data source field to true.

JavaScript
var menuItems = [
    {text: "item1"},
    {text: "item2", selected: true},
    {text: "item3", selectable: false },
];

To entirely prohibit an end user from selecting menu items, set the widget's allowSelection option to false.

HTML
<div data-bind="dxMenu: { 
        dataSource: menuItems, 
        allowSelection: false
    }">
</div>

Handle Item Events

Menu widgets include options that allow you to handle item clicking and selecting.

  • itemClickAction
    An action performed when a menu item is clicked.
  • itemSelectAction
    An action performed when a menu item is selected.

In addition, you can handle events that are raised when you show\hide a submenu. For this purpose, assign callback functions to the following widget configuration options.

  • showingAction
    An action performed before a submenu is shown.
  • shownAction
    An action performed when a submenu menu is shown.
  • hidingAction
    An action performed before a submenu is hidden.
  • hiddenAction
    An action performed when a submenu menu is hidden.
HTML
<div data-bind="dxMenu: { 
    dataSource: menuItems, 
    itemClickAction: itemClickHandler;
    shownAction: shownHandler
}">
</div>
JavaScript
itemClickHandler = function (data) {
    alert("Item is clicked");
}
shownHandler= function (data) {
    alert("Submenu is shown");
}

List of Menu Widgets

The following are DevExtreme UI menu widgets.

dxMenu

The dxMenu widget provides an easy and quick navigation. It consists of an array of root items, each of which can have one or several subitems. You can customize widget appearance and behavior if your task requires.

To set the required array of items for this widget, use the dataSource configuration option. For details on data binding, refer to the Data Binding topic in this article. In addition, learn other common tasks that can be performed for this widget.

Visual Elements

dxMenu Visual Elements

Orientation of root items

Menu orientation sets an order in which root items are displayed. By default, root items are displayed in a line. This orientation is called horizontal. You can set a vertical orientation. In this instance, root items are displayed in a column. To set an orientation, use the orientation option.

HTML
<div data-bind="dxMenu: { 
        dataSource: menuItems, 
        orientation: 'vertical'
    }">
</div>

Submenu display mode

By default, the first submenu is displayed when clicking a root item. You can change this behavior and display the first submenu when hovering a root item. For this purpose, set the showFirstSubmenuMode option to the 'hover' or 'hoverStay' value.

When a menu has several levels of subitems, each next submenu is displayed at the same event as the first one. To set another event, use the showSubmenuMode option.

HTML
<div data-bind="dxMenu: { 
        dataSource: menuItems, 
        showFirstSubmenuMode: 'onhover', 
        showSubmenuMode: 'onclick' 
    }">
</div>

Direction for submenus

By default, the first submenu is displayed at the bottom of a root item, when the widget's orientation is horizontal, and to the right, when the orientation is vertical. You can display the first submenu at the top of the root item for the horizontal orientation and to the left for the vertical orientation. For this purpose, set the submenuDirection option to 'top' or 'left', respectively.

HTML
<div data-bind="dxMenu: { 
        dataSource: menuItems, 
        orientation: 'vertical', 
        direction: 'left'
    }">
</div>

dxContextMenu

The dxContextMenu widget displays a context menu and gives you full control over the appearance and behavior of menu items at any nesting level.

To set the required array of items for this widget, use the dataSource configuration option. For details on data binding, refer to the Data Binding topic in this article. You can also review other common tasks that can be performed for this widget.

Visual Elements

dxMenu Visual Elements

Target element

To specify the element where the menu is displayed, use the target option. Leaving this option undefined is equivalent to assigning the window element.

HTML
<div id="targetElement"></div>
<div data-bind="dxContextMenu({
    target: "#targetElement",
    dataSource: contextMenuItems
}"></div>

First level display mode

By default, a context menu is displayed when you right-click the target element. If your task requires it, you can invoke a context menu in code. In such a case, set the visible option to true. You can also prohibit end users from displaying the context menu by setting the invokeOnlyFromCode option to true.

HTML
<div id="targetElement"></div>
<div data-bind="dxButton: { clickAction:  function () { { contextMenuVisible(true); } } }"></div>
<div id="myContextMenu" data-bind="dxContextMenu({
    target: "#targetElement",
    dataSource: contextMenuItems,
    invokeOnlyFromCode: true,
    visible: contextMenuVisible
}"></div>
JavaScript
contextMenuVisible = ko.observable(false);

Menu positioning

When a context menu is displayed as a result of right-clicking the target element, it is positioned with its top left corner by the mouse pointer. When a context menu in invoked from code, it is positioned at the top left corner of the target element. You can set a custom position using the position option.

HTML
<div id="targetElement"></div>
<div data-bind="dxButton: { clickAction:  function () { { contextMenuVisible(true); } } }"></div>
<div id="myContextMenu" data-bind="dxContextMenu({
    target: "#targetElement",
    dataSource: contextMenuItems,
    invokeOnlyFromCode: true,
    visible: contextMenuVisible,
    position: {
        at: 'top right',
        my: 'top left'
    }
}"></div>
JavaScript
contextMenuVisible = ko.observable(false);

Secondary levels display mode

By default, sub-menus are displayed when hovering the mouse pointer over their parent element. To specify a different action, use the showSubmenuMode option.

HTML
<div id="targetElement"></div>
<div data-bind="dxContextMenu({
    target: '#targetElement',
    dataSource: contextMenuItems
    showSubmenuMode: 'onclick'
}"></div>