A jQuery plugin that provides a context menu (based on the standard jQueryUI menu widget).
- Define menus from
<ul>element or definition list (i.e.[{title: "Paste", cmd: "paste"}, ...]). - Themable using jQuery ThemeRoller.
- Supports delegation (i.e. can be bound to elements that don't exist at the time the context menu is initialized).
- Optional support for touch devices.
The latest release is available at npm Registry:
$ npm install ui-contextmenu
First, include dependencies:
- jQuery 1.7+ (1.10 or later recommended)
- jQuery UI 1.9+ (at least core, widget, menu), 1.11+ recommended
- One of the ThemeRoller CSS themes or a custom one
- jquery.ui-contextmenu.js (also available as CDN on jsdelivr or cdnjs)
<head>
<link href="//code.jquery.com/ui/1.11.2/themes/smoothness/jquery-ui.css"
type="text/css" rel="stylesheet" />
<script src="//code.jquery.com/jquery-1.11.1.min.js" type="text/javascript"></script>
<script src="//code.jquery.com/ui/1.11.2/jquery-ui.min.js" type="text/javascript"></script>
<script src="assets/jquery.ui-contextmenu.min.js"></script>Assume we have some HTML elements that we want to attach a popup menu to:
<div id="container">
<div class="hasmenu">AAA</div>
<div class="hasmenu">BBB</div>
<div class="hasmenu">CCC</div>
</div>Now we can enable a context menu like so:
$("#container").contextmenu({
delegate: ".hasmenu",
menu: [
{title: "Copy", cmd: "copy", uiIcon: "ui-icon-copy"},
{title: "----"},
{title: "More", children: [
{title: "Sub 1", cmd: "sub1"},
{title: "Sub 2", cmd: "sub1"}
]}
],
select: function(event, ui) {
alert("select " + ui.cmd + " on " + ui.target.text());
}
});The delegate option defines a CSS selector, which is evaluated for all
elements inside the context element (#container in our example).
In order to attach menus to all matching elements on the page that have
class="hasmenu", we may use document as context:
$(document).contextmenu({
delegate: ".hasmenu",
...
});Note: only one contextmenu widget instance can be bound to one element.
The menu options may contain a (nested) array of entry defiitions.
Following a list of available properties:
- action
-
Type:
Function, default: n.a.
Optional callback that will be executed when the entry is selected. - addClass
-
Type:
String, default:""
Additional class name(s) to be added to the entries <li> element. Separate multiple class names with a space.
Custom CSS may be applied like.ui-menu .my-class { color: red; }. - cmd
-
Type:
String, default:""
Optional identifier associated with the menu entry. It can later be accessed in the select event asui.cmd. - data
-
Type:
Object, default:{}
Optional hash of additional properties that will be added to the entry's data attribute.
It can later be accessed in the select event asui.item.data(). - disabled
-
Type:
Boolean, default:false
Pass true to disable the entry. - title
-
Type:
String, default:""
The displayed name of the menu entry. Use dashes ("---") to define a separator. - uiIcon
-
Type:
String, default: ""
If defined, an icon is added to the menu entry. For example passing"ui-icon-copy"will generate this element:<span class='ui-icon ui-icon-copy' />.
See also <Icon Overview.
Instead of handling all menu commands in the select event, it is also possible
to attach callbacks directly to menu entries:
$(document).contextmenu({
delegate: ".hasmenu",
menu: [
{title: "Copy", uiIcon: "ui-icon-copy", action: function(event, ui){
alert("Copy " + ui.target.text());
}
},
...
});In this case menu must point to the markup:
$(document).contextmenu({
delegate: ".hasmenu",
menu: "#options",
select: function(event, ui) {
...
}
});We also have to provide some HTML markup that defines the context menu structure, see jQueryUI menu for details:
<ul id="options" class="ui-helper-hidden">
<li data-command="copy"><span class="ui-icon ui-icon-copy"></span>Copy</li>
<li data-command="paste" class="ui-state-disabled">Paste</li>
<li>----</li>
<li>More
<ul>
<li data-command="sub1">Sub 1</li>
<li data-command="sub2">Sub 2</li>
</ul>
</li>
</ul>Note: until and including jQuery UI 1.10 the use of anchors (<a>) in menu
items was required:
<ul id="options" class="ui-helper-hidden">
<li data-command="copy"><a href="#"><span class="ui-icon ui-icon-copy"></span>Copy</a>
...
</ul>Often we need to modify the menu before it is displayed, in order to reflect the
current context.
This can be done in the beforeOpen event:
$(document).contextmenu({
delegate: ".hasmenu",
menu: [
{title: "Cut", cmd: "cut", uiIcon: "ui-icon-scissors"},
{title: "Copy", cmd: "copy", uiIcon: "ui-icon-copy"},
{title: "Paste", cmd: "paste", uiIcon: "ui-icon-clipboard", disabled: true },
...
],
beforeOpen: function(event, ui) {
var $menu = ui.menu,
$target = ui.target,
extraData = ui.extraData; // optionally passed when menu was opened by call to open()
// Optionally return false, to prevent opening the menu
// return false;
// En/disable single entries
$(document).contextmenu("enableEntry", "paste", false);
// Show/hide single entries
$(document).contextmenu("showEntry", "cut", false);
// Redefine the title of single entries
$(document).contextmenu("setEntry", "copy", "Copy '" + $target.text() + "'")
// Redefine all attributes of single entries
$(document).contextmenu("setEntry", "cut", {title: "Cuty", uiIcon: "ui-icon-heart", disabled: true});
// Redefine the whole menu
$(document).contextmenu("replaceMenu", [{title: "aaa"}, {title: "bbb"}, ...]);
// Redefine the whole menu from another HTML definition
$(document).contextmenu("replaceMenu", "#options2");
},
...
});- addClass
-
Type:
String, default:"ui-contextmenu"
This class is added to the outer ul element. - autoFocus
-
Type:
Boolean, default:false
Set keyboard focus to first menu entry on open. - autoTrigger
-
Type:
Boolean, default:true
Set `false` to prevent opening on a browser's `contextmenu` event, which is normally triggered by a mouse rightclick.
The menu can still be opened by calling the `open()` method. - delegate
-
Type:
String
A selector to filter the elements that trigger the context menu. - hide
-
Type:
Boolean | Number | String | Object, default:{ effect: "fadeOut", duration: "fast" }
Effect applied when hiding the popup.
See sample for possible option values. - ignoreParentSelect
-
Type:
Boolean, default:true
Iftrue, a click on a menu item that contains a sub-menu, will not trigger theselectevent. - menu
-
Type:
Object[] | String | jQuery
jQuery object or selector of HTML markup that defines the context menu structure (see jQueryUI menu for details).If an array of objects is passed, it will be used to generate such markup on the fly. - position
-
Type:
Object | Function,
default:{my: "left top", at: "center", of: event, collision: "fit"}
Define position where popup opens. A simple position may be passed.
Also a function may be specified, to recalculate position every time:
$("#container").contextmenu({ position: function(event, ui){ return {my: "left top", at: "left bottom", of: ui.target}; }, ... - preventContextMenuForPopup
-
Type:
Boolean, default:false
Prevent that a right click inside an open popup menu will open the browser's system context menu. - preventSelect
-
Type:
Boolean, default:false
Prevent accidental text selection of potential menu targets on doubleclick or drag. - show
-
Type:
Boolean | Number | String | Object, default:{ effect: "slideDown", duration: "fast"}
Effect applied when showing the popup.
See sample for possible option values. - taphold
-
Type:
Boolean, default:false
Open menu on taphold events, which is especially useful for touch devices (but may require external plugins to generatetapholdevents). - tooltip
-
Type:
String, optional
Add atitleattribute to the menu markup, which will be displayed as tooltip by most browser (or external plugins). - uiMenuOptions
-
Type:
Object, default:{}
Custom options passed to UI Menu, when the widget is created.
Especially useful to tweak the position of submenus.
- close()
-
Close context menu if open.
Call like$(...).contextmenu("close");. - enableEntry(cmd, flag)
-
Enable or disable the entry. `flag` defaults to `true`
Call like$(...).contextmenu("enableEntry", "paste", false);. - getMenu()
-
Return the jQuery object for the menu's
ULelement. - isOpen()
- Return true if popup is visible.
- open(target[, extraData])
-
Open context menu on a specific target (target (as a jQuery object) must match the options.delegate filter).
Call like$(...).contextmenu("open", $(target)[, extraData]);. Optional `extraData` will be available in event handlers asui.extraData. - replaceMenu(menu)
-
Replace the whole menu definition.
Call like$(...).contextmenu("replaceMenu", "#menu2");. or$(...).contextmenu("replaceMenu", [{title: "aaa"}, {title: "bbb"}, ...]);. - setEntry(cmd, data)
-
Redefine menu entry (title or all of it).
`data` may be a title string or a menu definition object.
Call like$(...).contextmenu("setEntry", "paste", "Paste link");. - showEntry(cmd, flag)
-
Show or hide the entry. `flag` defaults to `true`
Call like$(...).contextmenu("showEntry", "paste", false);.
jquery-contextmenu exposes events from jQueryUI menu: blur, create, focus, select.
However, since the event.target parameter contains the menu item, we additionally pass the element
that was right-clicked in ui.target.
Events may be handled by passing a handler callback option:
$("#container").contextmenu({
[...]
select: function(event, ui) {
alert("select " + ui.cmd + " on " + ui.target.text());
}
});Alternatively a handler may be bound, so this is equivalent:
$("#container").bind("contextmenuselect", function(event, ui) {
alert("select " + ui.cmd + " on " + ui.target.text());
}- beforeOpen(event, ui)
-
Triggered just before the popup menu is opened.
Returnfalseto prevent opening.
This is also a good place to modify the menu (i.e. hiding, disabling, or renaming entries, or replace the menu altogether). - blur(event, ui)
- Triggered when the menu loses focus (original jQuery UI Menu event).
- close(event)
- Triggered when the menu is closed.
- create(event, ui)
- Triggered when the contextmenu widget is created.
- createMenu(event, ui)
- Triggered when the popup menu is created (original jQuery UI Menu `create` event).
- focus(event, ui)
- Triggered when a menu gains focus or when any menu item is activated (original jQuery UI Menu event).
- open(event)
- Triggered when the menu is opened.
- select(event, ui)
-
Triggered when a menu item is selected.
ui.cmdcontains the command id. Returnfalseto prevent closing the menu.
Simply add a tag of your choice to the title (for example <kbd>)
$(document).contextmenu({
delegate: ".hasmenu",
menu: [
{title: "Edit title<kbd>[F2]</kbd>", cmd: "rename"},
{title: "Copy <kbd>[Ctrl+C]</kbd>", cmd: "copy"}, ...
],and make it right aligned via CSS:
.ui-menu kbd {
float: right;
}In order open a context menu with the keyboard, make sure the target elements
are tabbable, for example by adding a tabindex="0" attribute.
Also make sure the autoFocus: true option is set.
This will allow to Use Tab and the Windows Menu keys.
$(document).contextmenu({
...
beforeOpen: function(event, ui) {
// Immediate menu changes
$(document).contextmenu("setEntry", "test", "(loading...)");
// Menu opens, then we submit a request and wait for the resonse
$.ajax({
...
}).done(function(data) {
// Modify the menu from the ajax response. The menu will be updated
// while open
$(document).contextmenu("setEntry", "test", {
title: "New entry", cmd: "test",
children: [ ... ]
});
});
},Alternatively we can delay the opening until the response arrives:
$(document).contextmenu({
...
beforeOpen: function(event, ui) {
var dfd = new $.Deferred();
$.ajax({
...
}).done(function(data) {
// Modify the menu from the ajax response. The menu will be opened
// afterwards
$(document).contextmenu("setEntry", "test", {
title: "New entry", cmd: "test",
children: [ ... ]
});
dfd.resolve(); // Notify about finished response
});
// Return a promise to delay opening until an async response becomes
// available
ui.result = dfd.promise();
},Thanks to all contributors.
