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.

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" }
        ]
    }
];

var menuOptions = { dataSource: menuItems }

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. In addition, the default item template supports the beginGroup field that specifies whether or not a group separator is displayed over the item. Set this field to true to display a separator.

JavaScript
var menuItems = [
    {
        iconSrc: '/Content/images/doc/14_2/PhoneJS/menus/VSIntegration.png',
        text: 'VS Integration',
    },
    {
        iconSrc: '/Content/images/doc/14_2/PhoneJS/menus/SPAFramework.png',
        text: 'SPA Framework',
        beginGroup: true,
    },
    {
        iconSrc: '/Content/images/doc/14_2/PhoneJS/menus/UIWidgets.png',
        text: 'UI Widgets',
    },
    . . .
]

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 an 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 selectionMode option to none.

JavaScript
var menuOptions =  { 
    dataSource: menuItems, 
    selectionMode: none
}

Handle Item Events

Menu widgets include options that allow you to handle item clicking and selecting. Here they are:

  • onItemClick
    An action performed when a menu item is clicked.
  • onSelectionChanged
    An action performed when a menu item is selected or unselected.
JavaScript
var menuOptions =  { 
    dataSource: menuItems, 
    onItemClick: function (data) {
        alert("Item is clicked");
    }
}

List of Menu Widgets

The following are DevExtreme UI menu widgets.

dxMenu

The dxMenu widget provides 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 it.

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.

View Demo

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.

JavaScript
var menuOptions = { 
    dataSource: menuItems, 
    orientation: 'vertical'
}

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.

JavaScript
var menuOptions = { 
    dataSource: menuItems, 
    showFirstSubmenuMode: 'onhover', 
    showSubmenuMode: 'onclick' 
}

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 horizontal orientation and to the left for vertical orientation. For this purpose, set the submenuDirection option to 'top' or 'left', respectively.

JavaScript
var menuOptions = { 
    dataSource: menuItems, 
    orientation: 'vertical', 
    direction: 'left'
}

Handle submenu events

The dxMenu widget enables you to handle events that are raised when you show or hide a submenu. For this purpose, assign callback functions to the following widget configuration options.

JavaScript
var menuOptions = { 
    dataSource: menuItems, 
    onSubmenuShown: function(e){
        //process submenuShown event
    },
    onSubmenuHidden: function(e){
        //process submenuHidden event
    }
}

Keyboard Support

An end-user can use the following keys to interact with the widget.

  • Left arrow
    Closes the current submenu and highlights its parent item.

  • Right arrow
    Expands the submenu of the highlighted item.

  • Home/End
    Highlights the first/last item of the current submenu.

  • Esc
    Closes the popup window and removes focus from the widget.

  • Space
    Select the highlighted element.

  • Enter
    Perform a click on the highlighted element.

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.

View Demo

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.

JavaScript
var contextMenuOptions = {
    target: "#targetElement",
    dataSource: contextMenuItems
}

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.

The dxContextMenu widget includes the show() and hide() methods, which show and hide the widget respectively. To access a widget method, obtain the widget instance first.

JavaScript
var buttonOptions = { 
    onClick:  function () {
        // Get the widget instance
        ...
        contextMenuInstance.show();
    }
};
var contextMenuOptions = {
    target: "#targetElement",
    dataSource: contextMenuItems,
    invokeOnlyFromCode: true      
};

You can prohibit end users from displaying the context menu by setting the invokeOnlyFromCode option to true.

NOTE
To change widget visibility, you can also use the toggle(showing) method, which displays or hides the widget depending on the value of the showing parameter.

Another way is to use the visible option. In MVVM approach, provide two-way binding to the option to show or hide the widget depending on the variable value. To show or hide the widget, assign true or false to the appropriate field respectively.

Angular Approach
HTML
<div id="targetElement"></div>
<div dx-button="{ onClick:  function () { contextMenuVisible = true; } }"></div>
<div dx-context-menu="{
    target: "#targetElement",
    dataSource: contextMenuItems,
    invokeOnlyFromCode: true,
    { bindingOptions: { visible: contextMenuVisible } }
}"></div>
JavaScript
function Controller($scope) {
    $scope.contextMenuVisible = false;
    //...
}
Knockout Approach
HTML
<div id="targetElement"></div>
<div data-bind="dxButton: { onClick:  function () { { contextMenuVisible(true); } } }"></div>
<div id="myContextMenu" data-bind="dxContextMenu({
    target: "#targetElement",
    dataSource: contextMenuItems,
    invokeOnlyFromCode: true,
    visible: contextMenuVisible
}"></div>
JavaScript
var viewModel = {
    contextMenuVisible = ko.observable(false);
    //...
}
ko.applyBindings(viewModel);

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.

JavaScript
var contextMenuOptions = {
    target: '#targetElement',
    dataSource: contextMenuItems
    showSubmenuMode: 'onclick'
}

Handle menu events

The dxContextMenu widget enables you to handle events that are raised when you show or hide the menu. For this purpose, assign callback functions to the following widget configuration options.

  • onShowing
    Performed before a menu is shown.
  • onShown
    Performed when a menu menu is shown.
  • onHiding
    Performed before a menu is hidden.
  • onHidden
    Performed when a menu menu is hidden.
JavaScript
var contextMenuOptions = { 
    dataSource: menuItems, 
    onShown: function(e){
        //process shown event
    },
    onHidden: function(e){
        //process hidden event
    }
}

Keyboard Support

An end-user can use the following keys to interact with the widget.

  • Left arrow
    Closes the current submenu and highlight its parent item.

  • Right arrow
    Expands the submenu of the highlighted item.

  • Home/End
    Highlights the first/last item of the current submenu.

  • Esc
    Hides the menu.

  • Space
    Selects the highlighted element.

  • Enter
    Performs a click on the highlighted element.