jQuery contextMenu plugin & polyfill

This repository now has a new maintainer

IMPORTANT: 2.0.0 is release and has change the default names of the icon classes in order to stop CSS conflicts with frameworks which define the class 'icon'.

$.contextMenu is a management facility for - you guessed it - context menus. It was designed for an application where there are hundreds of elements that may show a context menu - so intialization speed and memory usage are kept fairly small. It also allows to register context menus without providing actual markup, as $.contextMenu generates DOMElements as needed.

features - demo - documentation

Dependencies

jQuery 1.8.2
jQuery UI position (optional but recommended)

Usage

$.contextMenu({
    // define which elements trigger this menu
    selector: ".with-cool-menu",
    // define the elements of the menu
    items: {
        foo: {name: "Foo", callback: function(key, opt){ alert("Foo!"); }},
        bar: {name: "Bar", callback: function(key, opt){ alert("Bar!") }}
    }
    // there's more, have a look at the demos and docs...
});

have a look at the demos.

HTML5 Compatibility

Firefox 8 implemented contextmenu using the <menuitem> tags for menu-structure. The specs however state that <command> tags should be used for this purpose. $.contextMenu accepts both.

Firefox 8 does not yet fully implement the contextmenu specification (Ticket #617528). The elements a, button, input and option usable as commands are being ignored altogether. It also doesn't (optically) distinguish between checkbox/radio and regular commands (Bug #705292).

Note: While the specs note <option>s to be renderd as regular commands, $.contextMenu will render an actual <select>. import contextMenu from HTML5 <menu>:

$.contextMenu("html5");

Interaction Principles

You're (obviously) able to use the context menu with your mouse. Once it is opened, you can also use the keyboard to (fully) navigate it.

↑ (up) previous item in list, will skip disabled elements and wrap around
↓ (down) next item in, will skip disabled elements and wrap around
→ (right) dive into sub-menu
← (left) rise from sub-menu
↵ (return) invoke command
⇥ (tab) next item or input element, will skip disabled elements and wrap around
⇪ ⇥ (shift tab) previous item or input element, will skip disabled elements and wrap around
⎋ (escape) close menu
⌴ (space) captured and ignore to avoid page scrolling (for consistency with native menus)
⇞ (page up) captured and ignore to avoid page scrolling (for consistency with native menus)
⇟ (page down) captured and ignore to avoid page scrolling (for consistency with native menus)
↖ (home) first item in list, will skip disabled elements
↘ (end) last item in list, will skip disabled elements

Besides the obvious, browser also react to alphanumeric key strokes. Hitting r in a context menu will make Firefox (8) reload the page immediately. Chrome selects the option to see infos on the page, Safari selects the option to print the document. Awesome, right? Until trying the same on Windows I did not realize that the browsers were using the access-key for this. I would've preferred typing the first character of something, say "s" for "save" and then iterate through all the commands beginning with s. But that's me - what do I know about UX? Anyways, $.contextMenu now also supports accesskey handling.

Authors

Björn Brala
Rodney Rehm (original creator)
Christiaan Baartse (single callback per menu)
Addy Osmani (compatibility with native context menu in Firefox 8)

License

$.contextMenu is published under the MIT license

Special thanks

Font-Awesome icons used from encharm/Font-Awesome-SVG-PNG.

Changelog

Unreleased

Remove executable bit from jquery.contextMenu.js (thanks @jacknagel)
Fixed a problem there was when using a function for icons (thanks @RareDevil)
Fixed a problem where submenus resized wrong (thanks @RareDevil)
Fixed a problem where the contextmenu would open another menu (thanks @RareDevil) - (Issue #252 and Issue #293)

2.0.0 (October 28th 2015)

This version changes the default names of the icon classes in order to stop CSS conflicts with frameworks which define the class 'icon'. In order to keep the icon names the same as before this change you can change the defaults on the classnames for the icons (docs on classNames option). The classnames will probably be "context-menu-icon-*" as proposed earlier by @rodneyrehm.
You can not use SASS to customize your contextmenu. The gulp command build-icons takes all the SVG icons from src/icons and builds them into a font. In order to this we needed to break backwards compatibility. This does mean the new CSS does not have the old .icon class defined which makes it a lot more stable within CSS frameworks. The first revision of the documentation is found here.
The 1.x branch will be maintained for a while with bugfixes. But support for 1.x will be dropped in the coming months.
Reverted the change from 1.7.0: .html() changed back to .text() since it is an security issue (thanks @arai-a)

1.10.1 (October 25th 2015)

Added gulp command (integration-test-paths) to change the paths in the integration tests to the correct path after they are overwritten by the documentation generator.
Make sure the contextmenu is not outside the client area by (thanks to @arai-a)
Update jQuery dependecy so that it will not result in double installation of jQuery when using npm (thanks to @fredericlb)

1.9.1 (October 11th 2015)

Fixed a bug where the classNames options would fail on a submenu.
New documentation site and generation using couscous

1.9.0 (October 1st 2015)

Make classes configurable for those that can easily conflict. See the docs on classNames option. This also prepares to change classnames to non conflicting defaults so the hassle with frameworks as bootstrap will stop.
Fix for handling of seperator string. It threw an error on the protected property of String.$node
Fix for opening the contextmenu at coordinate 0,0 (by Andreme)
Fixed check for jQuery UI (Issue #182)
Updated doc for function argument for icon

1.8.1 (September 14th 2015)

Updated readme.
Updated dist files

1.8.0 (September 14th 2015) - dist files not updated!

Added dist folder with compiled JS and CSS, added these files to package and bower configuration.
Fixed doc link for jQuery UI position (Issue #274)
Item icon can now be a callback to dynamically decide on icon class. - (Issue #158, Issue #129, Issue #151, Issue #249)
Small fix to calculating width and height on screen edges when padding is present.

1.7.0 (August 29th 2015)

Touch support optimisations (by kccarter76)
changed .text to .html so there are no extra span's fixed - (Issue #252)
added visibility callback to item definition
copy the HTML5 icon attribute when creating from HTML5 elements
growing menu when opening multiple times fixed - (Issue #197)
fixed failure to run tests

1.6.8 (August 18th 2015)

changes for new maintainer

1.6.7 (May 21st 2015)

looking for maintainer note
publish to npm

1.6.6 (July 12th 2014)

fixing bower manifest

1.6.5 (January 20th 2013)

fixing "opening a second menu can break the layer" - (Issue #105)

1.6.4 (January 19th 2013)

fixing jQuery plugin manifest, again. yep. I'm that kind of a guy. :(

1.6.3 (January 19th 2013)

fixing jQuery plugin manifest

1.6.2 (January 19th 2013)

fixing "menu won't close" regression introduced by 1.6.1

1.6.1 (January 19th 2013)

fixing potential html parsing problem
upgrading to jQuery UI position v1.10.0
replaced CRLF by LF (no idea how this happened in the first place...)
adding options.reposition to dis/allow simply relocating a menu instead of rebuilding it (Issue #104)

1.6.0 (December 29th 2012)

adding DOM Element bound context menus - (Issue 88)
adding class context-menu-active to define state on active trigger element - (Issue 92)
adding demo for TouchSwipe activation
adding export of internal functions and event handlers - (Issue 101)
fixing key "watch" might translate to Object.prototype.watch in callbacks map - (Issue 93)
fixing menu and submenu width calculation - (Issue 18)
fixing unused variables - (Issue 100)
fixing iOS "click" compatibility problem - (Issue 83)
fixing separators to not be clickable - (Issue 85)
fixing issues with fixed positioned triggers (Issue 95)
fixing word break problem - (Issue 80)

1.5.25 (October 8th 2012)

upgrading to jQuery 1.8.2 (Issue 78)
upgrading to jQuery UI position 1.9.0 RC1 (Issue 78)

1.5.24 (August 30th 2012)

adding context menu options to input command events (Issue 72, dtex)
code cosmetics for JSLint

1.5.23 (August 22nd 2012)

fixing reposition/close issue on scrolled documents (Issue 69)
fixing jQuery reference (Issue 68)

1.5.22 (July 16th 2012)

fixing issue with animation and remove on hide (Issue #64)

1.5.21 (July 14th 2012)

fixing backdrop would not remove on destroy (Issue #63)

1.5.20 (June 26th 2012)

Note: git tag of version is v1.6.20?!

fixing backdrop would not position properly in IE6 (Issue #59)
fixing nested input elements not accessible in Chrome / Safari (Issue #58)

1.5.19

Note: git tag of version is missing...?!

fixing sub-menu positioning when $.ui.position is not available (Issue #56)

1.5.18

Note: git tag of version is missing...?!

fixing html5 <menu> import (Issue #53)

1.5.17 (June 4th 2012)

fixing options to default to options.trigger = "right"
fixing variable name typo (Within Issue #51)
fixing menu not closing while opening other menu (Within Issue #51)
adding workaround for contextmenu-bug in Firefox 12 (Within Issue #51)

1.5.16 (May 29th 2012)

added vendor-prefixed user-select to CSS
fixed issue with z-indexing when <body> is used as a trigger (Issue #49)

1.5.15 (May 26th 2012)

allowing to directly open another element's menu while a menu is shown (Issue #48)
fixing autohide option that would not properly hide the menu

1.5.14 (May 22nd 2012)

options.build() would break default options (Issue #47)
$.contextMenu('destroy') would not remove backdrop

1.5.13 (May 4th 2012)

exposing $trigger to dynamically built custom menu-item types (Issue #42)
fixing repositioning of open menu (formerly accidental re-open)
adding asynchronous example
dropping ignoreRightClick in favor of proper event-type detection

1.5.12 (May 2nd 2012)

prevent invoking callback of first item of a sub-menu when clicking on the sub-menu-item (Issue #41)

1.5.11 (April 27th 2012)

providing opt.$trigger to show event (Issue #39)

1.5.10 (April 21st 2012)

ignoreRightClick would not prevent right click when menu is already open (Issue #38)

1.5.9 (March 10th 2012)

If build() did not return any items, an empty menu was shown (Issue #33)

1.5.8 (January 28th 2012)

Capturing Page Up and Page Down keys to ignore like space (Issue #30)
Added Home / End keys to jump to first / last command of menu (Issue #29)
Bug hitting enter in an <input> would yield an error (Issue #28)

1.5.7 (January 21st 2012)

Non-ASCII character in jquery.contextMenu.js caused compatibility issues in Rails (Issue #27)

1.5.6 (January 8th 2012)

Bug contextmenu event was not passed to build() callback (Issue #24)
Bug sub-menu markers would not display properly in Safari and Chrome (Issue #25)

1.5.5 (January 6th 2012)

Bug Internet Explorer would not close menu when giving input elements focus (Issue #23)

1.5.4 (January 5th 2012)

Bug not set z-index of sub-menus might not overlap the main menu correctly (Issue #22)

1.5.3 (January 1st 2012)

Bug console.log is undefined

1.5.2 (December 25th 2012)

Bug sub-menus would not properly update their disabled states (Issue #16) [again…]
Bug sub-menus would not properly adjust width accoring to min-width and max-width (Issue #18)

1.5.1 (December 18th 2011)

Bug sub-menus would not properly update their disabled states (Issue #16)

1.5 (December 13th 2011)

Added dynamic menu creation (Issue #15)

1.4.4 (December 12th 2011)

Bug positioning <menu> when trigger element is position:fixed (Issue #14)

1.4.3 (December 11th 2011)

Bug key handler would caputure all key strokes while menu was visible (essentially disabling F5 and co.)

1.4.2 (December 6th 2011)

Bug opt.$trigger was not available to disabled callbacks
jQuery bumped to 1.7.1

1.4.1 (November 9th 2011)

Bug where <menu> imports would not pass action (click event) properly

1.4 (November 7th 2011)

Upgraded to jQuery 1.7 (changed dependecy!)
Added internal events contextmenu:focus, contextmenu:blur and contextmenu:hide
Added custom <command> types
Bug where className wasn't properly set on <menu>

1.3 (September 5th 2011)

Added support for accesskeys
Bug where two sub-menus could be open simultaneously

1.2.2 (August 24th 2011)

Bug in HTML5 import

1.2.1 (August 24th 2011)

Bug in HTML5 detection

1.2 (August 24th 2011)

Added compatibility to <menuitem> for Firefox 8
Upgraded to jQuery 1.6.2

1.1 (August 11th 2011)

Bug #1 TypeError on HTML5 action passthru
Bug #2 disbaled callback not invoked properly
Feature #3 auto-hide option for hover trigger
Feature #4 option to use a single callback for all commands, rather than registering the same function for each item
Option to ignore right-click (original "contextmenu" event trigger) for non-right-click triggers

1.0 (July 7th 2011)

Initial $.contextMenu handler

GitHub30/jQuery-contextMenu