@ne1410s/menu
v0.1.98
Published
Lightweight ES context menu.
Downloads
936
Maintainers
Readme
@ne1410s/demo
A lightweight and customisable context menu.
<ne14-menu>
<li>Hello world</li>
<li class="split"></li>
<li>
<span>Nested Item</span>
<ul>
<li>Item 1</li>
<li class="disabled">Item 2</li>
</ul>
</li>
</ne14-menu>
What Does It Do?
- Provides a context menu with sub-menu support, based on original markup
- Supports
<a href target>
tags to navigate in new tab or in current tab accordingly - Appears and behaves like a browser's "default" context menu
- Supports item disabling and hiding alike
- Provides splitters for logical grouping, the presence of which is monitored to strip out orphaned zones / multiple splitters from appearing
- Supports unicode charset (hex) for icons at either side of the item text, and/or
<img>
tags - Displays shortcut keys (the implementation of which is left to the author)
- Inherits the font family and size (size is ~2/3 that of the html root)
How Do I Use It?
- Include the umd script in the head
<script src="PATH_TO_UMD_SCRIPT"></script>
- Declare (or programatically construct) your markup (using below guide)
- Whatever click handling you have will be invoked when items are clicked
- Position the menu html inside whichever container element(s) the menu applies
- Yes you can easily have different menus for different zones!
- If your menu doesn't need to change, that's all you need to do
- But if you did wish to effect a change dynamically, then just alter the structure accordingly and call
.reload()
on the menu instance
Guidance, Please
- Specify only
<li>
nodes as direct descendants - Provide some kind of node text (e.g. either directly or in a
<p>
or<span>
) - Use
li.split
to make a divider line - Use
li.disabled
to "grey-out" an item - Use
li.hidden
to conceal an item entirely - Images & font icons can be included either side of the menu item text:
- Icons are unicode charset hex references, specified on the
<li>
as eitherdata-char-left
/data-char-right
. If present, these supersede images. If not present: ... - The first nested
<img>
(to not have aright
class) is used on the left - The first nested
<img class='right'>
is used on the right
- Icons are unicode charset hex references, specified on the
- Use
aria-keyshortcuts
to show a command shortcut (this is not implemented by this component however, it is just to display anything that has been)
NB: To extend this library, or import it in node js, use: npm i -S @ne1410s/menu
Attributes
- There are no bespoke attributes exposed in this element
Events
const menu = document.querySelector('ne14-menu');
// As mentioned, each item click is propagated on the original element.
// Instead of (or as well as) dedicated handling, one may also proceed via the
// following generic selection handler
menu.addEventListener('itemselect', (event) => {
console.log('Item Selected!', event);
});
itemselect
occurs when an item is clicked. The custom event detail contains the text of the menu item, its in-menu reference and the original html elementitemhover
anditemunhover
occur when mouse enters or leaves an itemmenuopen
andmenuclose
occur when the menu is opened or closed
Methods
open()
Opens the menu (after closing any others)close()
Closes the menureload()
Recreates the menu according to its current content
Properties
- There are no bespoke properties exposed in this element
CSS Variables
Some degree of custom styling can be optionally provided, by way of css variables:
/* Example of 'dark mode': */
ne14-menu {
--bg: #333;
--border: 1px solid #888;
--box-shadow: 2px 2px 3px #333;
--hover-item-bg: #666;
--fg: #eee;
--disabled-fg: #666;
}
--bg
Background for the menu. Defaults to:#fff
--border
Border for the menu. Defaults to:1px solid #bbb
--box-shadow
Box shadow for the menu. Defaults to:2px 2px 3px #888
--font
Font for the menu. Defaults to:0.65em inherit
--fg
Color for menu items. Defaults to:#000
--disabled-fg
Color for disabled menu items. Defaults to:#bbb
--split-border
Border for split lines. Defaults to:--border
else1px solid #bbb
--hover-item-bg
Background color for items in the hover state. Defaults to:#bbb