Version 1.0.3

Installation

ContextMenu.js depends on two external scripts: jQuery & jQueryUI. If you don’t want to include all of jQuery UI’s widgets, at the bare minimum you will need to include jQueryUI Core and jQueryUI position. If you want to have icons you also need to include FontAwesome. Here is a basic document structure to get you started:

<!DOCTYPE html>
<html>
    <head>
        <title>ContextMenu.js Demo</title>
        <link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css" rel="stylesheet" />
        <link href="contextmenu.min.css" rel="stylesheet" />
        <script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
        <script src="https://code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>
        <script src="contextmenu.min.js"></script>
    </head>
    <body>
        <div id="contextmenu"></div>
    </body>
</html>

And then, attach a drop down menu to an element using jQuery:

$('#contextmenu').contextMenu({
    items: [
        {type: 'item', text: 'Cut', icon: 'fa fa-scissors'},
        {type: 'item', text: 'Copy', icon: 'fa fa-files-o'},
        {type: 'item', text: 'Paste', icon: 'fa fa-clipboard'},
        {type: 'divider'},
        {type: 'item', text: 'Delete', icon: 'fa fa-times'}
    ]
});

Menu Events

ContextMenu.js offers much more than just context menus. It can also be used to create drop down lists, navigations, and more. To achieve that, menus can be triggered by 5 different events: click, dblclick, hover, focus, and the default contextmenu. To set the triggering event, use the event option.

For the hover event, it is recommended to also set autoHide to a value different than the default 0, since the menu will be automatically hidden when the mouse leaves the element. Read more about automatic hiding below.
$('#contextmenu').contextMenu({
    event: 'click',
    items: [ ... ]
});

// Setting the event to 'hover' causes the menu to automatically hide immediately
$('#contextmenu').contextMenu({
    autoHide: 300, // Wait 300ms before hiding the menu
    event: 'hover',
    items: [ ... ]
});

Dynamic Event Binding

Context menus can be bound to dynamically created elements using the selector option. Simply call jQuery on an existing element (one that exists at the time of the call) and provide a selector string to the selector option for the dynamic element(s).

// Select any element that exists at the time of the call
$('html').contextMenu({ 
    // Selector string pointing to the dynamic element
    selector: '.dynamic-child', 
    items: [ ... ]
});

Transition Effects

There are 8 transition effects that can be used to show/hide the menu. Available transitions are slideTop, slideBottom, slideLeft, slideRight, flipHorizontal, flipVertical, fadeIn, and the default none. It is also possible to set the speed of the transition in milliseconds using the speed argument (defaults to 0).

$('#contextmenu').contextMenu({
    transition {
        speed: 300, // In milliseconds
        type: 'fadeIn'
    },
    items: [ ... ]
});

Menu Item Types

Menus can be constructed using one or more of the 4 available menu item types: divider, title, item, checkbox. The items option accepts an array of objects, each of which has a type key specifying the type of the item.

$('#contextmenu').contextMenu({
    items: [
        {type: 'title', text: 'File Controls'},
        {type: 'item', text: 'Cut', icon: 'fa fa-scissors'},
        {type: 'item', text: 'Copy', icon: 'fa fa-files-o'},
        {type: 'item', text: 'Paste', icon: 'fa fa-clipboard'},
        {type: 'divider'},
        {type: 'item', text: 'Delete', icon: 'fa fa-times'}
    ]
});

Divider

The divider component is a simple line used to divide the menu into different sections. It accepts no arguments.

{type: 'divider'}

Title

The title component is used to display static text inside the menu. It accepts the following arguments:

  • text  (string) Text/HTML to display as the title.
{type: 'title', text:'Title Text Goes Here'}

Item

The item component is used to create menu items that can have events bounded to them and have sub-menus. It accepts the following arguments:

  • text  (string) Text/HTML to display as the item’s text.
  • icon (string) A FontAwesome CSS class to use as the icon (or a custom CSS class for custom icons).
  • disabled (boolean) Set to true to disable the item. defaults to false.
  • click (function) A function to call when the item is clicked. Takes the current event as an argument.
  • hover  (function) A function to call when the item is hovered over. Takes the current event as an argument.
  • id  (string) The item’s element id. Leave blank for no id.
{
    type: 'item', 
    text: 'Paste', 
    icon: 'fa fa-clipboard', 
    disabled: false, 
    click: function(e) {}
    hover: function(e) {}
}

Checkbox

  • text  (string) Text/HTML to display as the checkbox’s text.
  • icon (string) A FontAwesome CSS class to use as the icon (or a custom CSS class for custom icons).
  • disabled (boolean) Set to true to disable the checkbox. defaults to false.
  • checked (boolean) The initial checkbox value. Set to true to mark the checkbox as checked. defaults to false.
  • click (function) A function to call when the checkbox is clicked (called after the checkbox is being toggled). Takes the current event as an argument.
  • hover  (function) A function to call when the checkbox is hovered over. Takes the current event as an argument.
  • id  (string) The item’s element id. Leave blank for no id.
{
    type: 'checkbox', 
    text: 'Checkbox Text', 
    icon: '', // Used in addition to the checkmark icon
    disabled: false, 
    checked: false,
    click: function(e) {}
    hover: function(e) {}
}

Item Events

Menu-Wide Item Events

Event listeners can be assigned to all menu items by using the click or hover options. The functions accepts the event’s data object as an argument. The this variable can be used to retrieve the calling item’s settings.

Note menu-wide events will automatically be assigned to all item/checkbox types. To distinguish between the, use this.type === 'item' or this.type === 'checkbox'
$('#contextmenu').contextMenu({
    click: function(e) {
        // 'this' refers to the clicked item
        alert('The item "'+this.text+'" was clicked');
    },
    items: [
        {type: 'item', text: 'Item 1'},
        {type: 'item', text: 'Item 2'},
        {type: 'item', text: 'Item 3'}
    ]
});

Item-Specific Events

Item event listeners can be set on a per-item basis. Item events are only applicable to item/checkbox types.

An item-specific event overrides a menu-wide event of the same type.
$('#contextmenu').contextMenu({
    click: function(e) {
        // 'this' refers to the clicked item
        alert('The item "'+this.text+'" was clicked');
    },
    items: [
        {type: 'item', text: 'Item 1'},
        {type: 'item', text: 'Item 2'},
        {type: 'item', text: 'Item 3', click: function(e){alert('Click event overridden by '+this.text);}}
    ]
});

Dynamic Items

Menus can be dynamically constructed each time a selected event has been triggered. This can be used to create event-specific menus on the fly. The menus are destroyed and reconstructed every time.

To dynamically create menu items, set the items option as a function instead of an array. The function should return an array of menu items and take the current event as an argument.

$('#contextmenu').contextMenu({
    items: function(e) {
        return [
            /* List of items */
        ]
    }
});

Positioning

Drop down menus can be positioned relative to the target element. The syntax used is similar to the one used by jQuery.position. For example, {my: 'left top', at: 'center bottom'} will position the menu’s top left corner at the bottom and center of the target element. Additionally, by setting at: 'mouse' the menu can be positioned according to the mouse coordinates.

If you want the menu to be repositioned when clicking on certain children of the target element, you can do that using the children argument that takes a selector string.

Notice that the menu will automatically be placed inside the screen if it collides with the window’s boundaries.
$('#contextmenu').contextMenu({
    position: {
        my: 'left top+5', // add 5px to the menu's top position
        at: 'center bottom', 
        children: '.target-element-child'
    },
    items: [ ... ]
});

Action Hooks

There are 3 actions that can be hooked to for running custom functions at specific times.

  • show – Triggered when the menu becomes visible. If another click is made on the target element, the menu will be repositioned, but the show hook will not be triggered again.
  • position – Triggered when the menu becomes visible, and every time it is repositioned. For example, when the menu is visible and another click on the target element is made, the menu will be repositioned and the position hook will be triggered.
  • hide  – Triggered when the menu becomes hidden (after the transition effect has been completed).
$('#contextmenu').contextMenu({
    items: [ ... ],
    hooks: {
        // Called when the menu is shown
        show: function(e) {},
        
        // Called when the menu is repositioned (also called every time the menu is shown)
        position: function(e){},

        // Called when the menu is hidden
        hide: function(e){}
    }
});

Methods

There are several methods that can be called after a context menu has been instantiated.

show

Opens the menu. Accepts the current event as an argument.

$('#myElement').click(function(e){
    $('#contextmenu').contextMenu('open',e);
});

hide

Closes the current menu. Accepts the current event as an argument.

$('#myElement').click(function(e){
    $('#contextmenu').contextMenu('close',e);
});

refresh

Refreshes the contents of the menu (as if the menu has been closed and reopened). applicable if the menu items are being generated dynamically.

$('#myElement').click(function(e){
    $('#contextmenu').contextMenu('refresh',e);
});

isVisible

Returns true if the menu is currently open.

$('#contextmenu').contextMenu('isVisible');

select

Select a menu item by its ID (item ID, not HTML ID).

// Select the first menu item
$('#contextmenu').contextMenu('select',0);

Auto Hiding

Menus can be set to automatically hide when the cursor moves out of them by setting the autoHide option to any number representing the delay in milliseconds. The default value of autoHide is false, disabling automatic hiding.

Note that menus that use hover as their triggering event are automatically hidden by default.
$('#contextmenu').contextMenu({
    autoHide: 500, // Time in milliseconds, 
                   // or 'false' to disable auto hiding
    items: [ ... ]
});

Menu Arrow

The menu arrow is a little triangle used for pointing towards the mouse position or the target element. The arrow’s position can be set by using the arrow  option. possible values are 'auto' , 'top' , 'bottom' , 'left' , 'right'  or false  for no arrow. Defaults to 'auto'.

$('#contextmenu').contextMenu({
    arrow: 'auto', // Or bottom, left, right, top (false for no arrow)
    items: [ ... ]
});

Options

Name Type Default Usage
maxHeight Number null The maximum height of the root element
minHeight Number null The minimum height of the root element
maxWidth Number null The maximum width of the root element
minWidth Number 160 The minimum width of the root element
height Number null The height of the root element
width Number null The width of the root element
class string null An optional CSS class to be added to the container element. Can be used to add custom styling.
event string 'contextmenu' The triggering event. One of 'contextmenu'  'click'  'dblclick'  'hover'  'focus'
selector string null Selector string pointing to a dynamically created element. Can be used for dynamic binding.
hooks object {show:null,hide:null,position:null} Functions to be called when different events take place. See actions hooks
position object {my:'left-25 top+5', at: 'mouse', children: false} The position of the context menu relative to the triggering element, using jQuery.position syntax. The children parameter takes a selector string pointing to children elements of the triggering element. If set, the children parameter will force the menu to reposition when that child element(s) is/are clicked.
autoHide Number false The number of milliseconds to wait before automatically hiding the menu. If set to false, the menu will not hide automatically.
transition Object { speed: 0, type: 'none' } The speed (in milliseconds) and type of the transition used to show/hide the menu. See transition effects for available transitions.
appendTo DOM Element document.body The element to append the context menu to.
arrow String 'auto' The position of the menu’s triangle arrow. See menu arrow.
items Array|Function [] An array of items or a function that takes the current event as an argument and returns a list of items. See dynamic items
click Function null General purpose click function (overridden by item’s click function)
hover Function null General purpose hover function (overridden by item’s hover function)

Spread the word about ContextMenu.js!