Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/georgianstan/vanilla-context-menu

An NPM package to create context menus written in vanilla JavaScript
https://github.com/georgianstan/vanilla-context-menu

Last synced: 5 months ago
JSON representation

An NPM package to create context menus written in vanilla JavaScript

Awesome Lists containing this project

README 

        
# Vanilla Context Menu





    issues

    forks

    stars

    license

    version




`vanilla-context-menu` - easily create context-menus using Vanilla JavaScript and integrate them in any web application



## Installation



### Browser CDN



```html



```



Where `@1.4.1` is the version that you want to use.



Then anywhere in your JavaScript code you can access the library with `window.VanillaContextMenu` or simply `VanillaContextMenu`.



### Via NPM



```bash

npm i vanilla-context-menu

```



Then anywhere in your code.



```javascript

import VanillaContextMenu from 'vanilla-context-menu';

```



## How to use it



```javascript

new VanillaContextMenu({

  scope: document.querySelector('main'),

  menuItems: [

    {

      label: 'Copy',

      callback: () => {

        // your code here

      },

    },

    'hr',

    {

      label: 'Paste',

      callback: pasteFunction,

    },

    {

      label: 'Cut',

      callback: pasteFunction,

      iconClass: 'fa fa-scissors', // this only works if you have FontAwesome icons

    },

    { label: 'Face', iconHTML: `face` // this only works if you have Google Material Icons icons },

  ],

});

```



## Configuration options



```typescript

VanillaContextMenu(configurableOptions: ConfigurableOptions):VanillaContextMenu

```



**ConfigurableOptions**



|       Option        | Required |        Type        |  Default  |                                                                    Description                                                                    |

| :-----------------: | :------: | :----------------: | :-------: | :-----------------------------------------------------------------------------------------------------------------------------------------------: |

|        scope        | **yes**  |    HTMLElement     | undefined |                                   The HTML element on which you want to bind the `contextmenu` event listener.                                    |

|      menuItems      | **yes**  |     MenuItem[]     | undefined |                                                              Menu items to be built.                                                              |

|     customClass     |    no    |       string       | undefined |                                             A custom CSS class that can be added to the context menu                                              |

|  customThemeClass   |    no    |       string       | undefined |            A custom CSS class that can be added to the context menu theme. A value for this property will exclude the `theme` option.             |

| preventCloseOnClick |    no    |      boolean       |   false   |                          If this variable is `true`, then the context menu will not close when its elements are clicked.                          |

| transitionDuration  |    no    |       number       |    200    |                        Duration of the context menu transition. Set this value to 0 if you want to disable the animation.                         |

|        theme        |    no    | 'black' \| 'white' |   black   | By default, the library provides two themes for the context menu: `black` and `white`. You can use this option to choose the one you want to use. |

|  normalizePosition  |    no    |      boolean       |    true   |  If true, the position of the contextmenu is bound to the scope. Otherwise the left top corner of the contextmenu is bound to the mouse position. |



**MenuItem**



```typescript

type MenuItem = MenuOption | 'hr';

```



**MenuOption**

| Option | Required | Type | Default | Description |

|:-------------------:|:--------:|:---------:|:---------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------:|

| label | **yes** | string | undefined | Menu option label. |

| iconClass | no | string | undefined | This property can be used to display an optional icon. It presents the CSS classes that will be added for the `` tag. |

| iconHTML | no | string | undefined | This property can be used to display an optional icon. It presents an HTML string that will be sanitized internally using [DOMPurify](https://www.npmjs.com/package/dompurify). |

| callback | no | (ev:MouseEvent) => any | undefined | Callback to be executed. The parameter `ev` is the MouseEvent that occurred when the `contextmenu` event was triggered |

| preventCloseOnClick | no | boolean | false | If this variable is `true`, then the context menu will not close when this menu option is clicked. A value set for this option, either `true` or `false` will override the global one. |

| nestedMenu | no | NestedMenuItem[] | undefined | Nested menu to be built.



**NestedMenuItem**



```typescript

export type NestedMenuItem = BaseMenuOption | 'hr';

export interface BaseMenuOption {

  label: string;

  callback?: (ev: MouseEvent) => unknown;

  iconClass?: string;

  iconHTML?: string;

  preventCloseOnClick?: boolean;

}

```



## API (3)



The following methods and properties are available through the class instance.



```ts

const myContextMenu = new VanillaContextMenu(...)

```



(1)



```ts

off(): void

```



This method will remove all event listeners that have been registered for the context-menu.



**!** It should be called when you want to deactivate the context menu or when the container item has been removed from the DOM.



(2)



```ts

updateOptions(configurableOptions: Partial): void

```



(3)



```ts

close(): void

```



This method closes the context-menu.



## Examples



### Define your own theme



```scss

.context-menu-orange-theme {

  background: #d35400;



  hr {

    background-color: #eee;

  }



  // text color for each item

  & > *:not(hr) {

    color: #eee;



    &:hover {

      background: #e67e22;

    }

  }

}

```



### Define your own CSS class for styling



```css

.custom-context-menu-cls {

  width: 100px !important;

  font-family: 'Roboto', sans-serif; /* DEFAULT -- font-family: 'Open Sans', sans-serif; */

}

```



```ts

const myContextMenu = new window.VanillaContextMenu({

  scope: ...,

  menuItems: [...],

  customThemeClass: 'context-menu-orange-theme',

  customClass: 'custom-context-menu-cls',

});

```



### Add icons for your menu itmes



Firstly you need to add an icon library inside your application and then you can use the `iconClass` property to specify the CSS classes that will be added for the `` tag.



The following example will add a FontAwesome scissors icon near the menu option **Cut**.



```javascript

new VanillaContextMenu({

  scope: document.querySelector('main'),

  menuItems: [

    {

      label: 'Cut',

      callback: pasteFunction,

      iconClass: 'fa fa-scissors', // this only works if you have FontAwesome icons

    },

  ],

});

```



You can check the `demo` file for more examples from [demo/index.html](https://github.com/GeorgianStan/vanilla-context-menu/blob/master/demo/index.html).



## Contributing



Pull requests and stars are always welcome. Please check the [guidelines](https://github.com/GeorgianStan/vanilla-context-menu/blob/master/CONTRIBUTING.md).



## Changelog



For project updates you can also reference the [changelog](https://github.com/GeorgianStan/vanilla-context-menu/blob/master/CHANGELOG.md).



## Stay in touch



[Discussions page](https://github.com/GeorgianStan/vanilla-context-menu/discussions)



## License



This project is licensed under the [MIT License](https://github.com/GeorgianStan/vanilla-context-menu/blob/master/LICENSE)