# vanilla-context-menu

> Easily create context menus using vanilla JavaScript and integrate them in any web application

Latest version **1.6.0** (published 2023-09-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install vanilla-context-menu
pnpm add vanilla-context-menu
yarn add vanilla-context-menu
bun add vanilla-context-menu
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.6.0 |
| Published | 2023-09-21 |
| First published | 2021-04-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 49.7 KB |
| Known vulnerabilities | 0 (+16 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 20 |
| Author | Stan Georgian |
| Maintainers | georgianstan |
| Keywords | javascript, context-menu, right-click menu, vanilla javascript, menu |

## Links

- npm: https://www.npmjs.com/package/vanilla-context-menu
- Repository: https://github.com/GeorgianStan/vanilla-context-menu
- Homepage: https://github.com/GeorgianStan/vanilla-context-menu#readme
- Issues: https://github.com/GeorgianStan/vanilla-context-menu/issues
- npm.io page: https://npm.io/package/vanilla-context-menu

## Dependencies (1)

- [dompurify](https://npm.io/package/dompurify.md) ^2.4.0

## Recent versions

- 1.6.0 (latest) — 2023-09-21
- 1.5.0 — 2023-09-01
- 1.4.2 — 2022-12-13
- 1.4.1 — 2022-12-13
- 1.4.0 — 2022-11-09
- 1.3.0 — 2022-09-20
- 1.2.2 — 2022-07-15
- 1.2.1 — 2022-07-15
- 1.2.0 — 2022-07-15
- 1.1.0 — 2022-06-25
- 1.0.1 — 2021-04-20
- 1.0.0 — 2021-04-20
- 0.0.1 — 2021-04-17

## README

# Vanilla Context Menu

<div style='text-align:center'>
    <img src='https://img.shields.io/github/issues/GeorgianStan/vanilla-context-menu' alt='issues'>
    <img src='https://img.shields.io/github/forks/GeorgianStan/vanilla-context-menu' alt='forks'>
    <img src='https://img.shields.io/github/stars/GeorgianStan/vanilla-context-menu' alt='stars'>
    <img src='https://img.shields.io/github/license/GeorgianStan/vanilla-context-menu' alt='license'>
    <img src='https://img.shields.io/github/package-json/v/GeorgianStan/vanilla-context-menu?color=%237146f9&logo=javascript' alt='version'>
</div>

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

## Installation

### Browser CDN

```html
<script src="https://unpkg.com/vanilla-context-menu@1.4.1/dist/vanilla-context-menu.js"></script>
```

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: `<span class="material-icons">face</span>` // 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 `<i></i>` 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 <sub style='font-size:15px'>(3)</sub>

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<ConfigurableOptions>): 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 `<i></i>` 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)

---
_Source: https://npm.io/package/vanilla-context-menu · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._