Skip to content
This repository has been archived by the owner on Aug 14, 2021. It is now read-only.

ApiRef

Jump to bottom
Martin Wendt edited this page Jan 23, 2018 · 19 revisions

jquery.ui-contextmenu - API documentation

Options

The context menu is initialized with an options hash like so:

$("#container").contextmenu({
  // Options:
  delegate: ".hasmenu",
  menu: [
    ...
    ],
  // Events:
  beforeOpen: function(event, ui) {
    ...
  },
  select: function(event, ui) {
    alert("select " + ui.cmd + " on " + ui.target.text());
  }
});

The following options are available:

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.
appendTo
Type: String | jQuery | Element, default: "body"
Parent element for generated <ul> markup.
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.
closeOnWindowBlur
Type: Boolean, default: true
Close menu when window loses focus, e.g. the user click into another frame.
delegate
Type: String, mandatory
A selector to filter the elements that trigger the context menu.
Examples:
".has-menu", "span.my-element,div.my-container",
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
If true, a click on a menu item that contains a sub-menu, will not trigger the select event.
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.
This option dynamically creates user-select: none CSS rules for the selector that was passed as delegate option.
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 generate taphold events).
uiMenuOptions
Type: Object, default: {}
Custom options passed to UI Menu, when the widget is created.
Especially useful to tweak the position of submenus.

Menu Entry Properties

Menu entries are defined as a (nested) list of options inside the global menu option:

$("#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());
  }
});

Following a list of available properties per menu entry:

action
Type: Function, default: n.a.
Optional callback that will be executed when the entry is selected.
This is an alternative to implementing the `select` event handler.
addClass
Type: String, default: ""
Additional class name(s) to be added to the entry's <li> element. Separate multiple class names with a space.
Custom CSS may be applied like .ui-menu .my-class { color: red; }.
(See also setClass.)
cmd
Type: String, default: ""
Optional identifier associated with the menu entry. It can later be accessed in the select event as ui.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 as ui.item.data().
disabled
Type: Boolean | Function, default: false
Pass true to disable the entry.
If a function(event, ui) is passed, it will be called on every menu open. Return values are true, false, or "hide", so it can also be used to temprarily remove entries from the menu.
hide
Type: Boolean, default: false
Pass true to hide the entry.
Note: this property is only evaluated by updateEntry().
isHeader
Type: Boolean, default: false
The entry will be displayed as a category header, i.e. styled with the `.ui-widget-header` class and not selectable.
NOTE: requires jQuery UI 1.11+
setClass
Type: String, default: ""
This option is only available for updateEntry().
Unlike addClass, existing previous custom classes are removed before new classes are added.
title
Type: String | Function, default: ""
The displayed name of the menu entry. Use dashes ("---") to define a separator.
Note that `title` may contain html markup, so make sure to escape external strings correctly!
If a function(event, ui) is passed, it will be called on every menu open. The returned string or object value will be used with setEntry().
tooltip
Type: String | Function, optional
Add a title attribute to the menu markup, which will be displayed as tooltip by most browser (or external plugins).
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.

Methods

Methods may be called like so: $(SELECTOR).contextmenu(METHOD, <args>)

For example:

$(document).contextmenu("enableEntry", "paste", false);

Following a list of available methods:

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);.
getEntry(cmd)
Return the jQuery object for the menu entry's <li> element. It contains the wrapper and potentially a nested <ul> element.
getEntryWrapper(cmd)
Return the jQuery object for the menu entry's wrapper element that contains title and icons.
For jQuery UI 1.12 this is a <div> tag inside the element's <li>, but the markup is different for jQuery UI 1.10 and 1.11.
getMenu()
Return the jQuery object for the menu's UL element.
isOpen()
Return true if popup is visible.
open(targetOrEvent[, extraData])
Open context menu on a specific target.
`targetOrEvent` may either be a target element (jQuery object) or a mouse event.
Note: the target object must match the options.delegate filter.
Call like $(...).contextmenu("open", $(target)[, extraData]);. Optional `extraData` will be available in event handlers as ui.extraData.
See also the wiki.
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 completely.
Call like $(...).contextmenu("setEntry", "paste", {title: "Paste link", uiIcon: "ui-icon-copy" });.
Note: in version 1.x this method
Note that `title` may contain html markup, so make sure to escape external strings correctly!
setIcon(cmd, icon)
A shortcut for updateEntry(cmd, {uiIcon: icon}).
setTitle(cmd, title)
A shortcut for updateEntry(cmd, {title: title}).
Note that `title` may contain html markup, so make sure to escape external strings correctly!
showEntry(cmd, flag)
Show or hide the entry. `flag` defaults to `true`
Call like $(...).contextmenu("showEntry", "paste", false);.
updateEntry(cmd, data)
Adjust the menu entry's properties.
Unlike setEntry(), this methode will leave properties untouched that are not listed in data. Pass `null` values to remove a property.
Call like $(...).contextmenu("updateEntry", "paste", {title: "Paste 'xxx' to 'yyy'"});.
Note that `title` may contain html markup, so make sure to escape external strings correctly!

Events

A few new events are triggered by jquery-contextmenu.

In addition, jquery-contextmenu exposes events from original jQueryUI menu plugin (blur, create, focus, select).
However, since the event.target parameter contains the menu item, we additionally pass the element that was right-clicked as 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").on("contextmenuselect", function(event, ui) {
    alert("select " + ui.cmd + " on " + ui.target.text());
});

Following a list of available events:

beforeOpen(event, ui)
Triggered just before the popup menu is opened.
Return false to 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, ui)
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, ui)
Triggered when the menu is opened.
select(event, ui)
Triggered when a menu item is selected.
ui.cmd contains the command id. Return false to prevent closing the menu.

Index

Clone this wiki locally