v-contextmenu

To use v-contextmenu in your Vue application, use the install function or the default export to register the contextmenu directive and all core components (VContextmenu, VContextmenuItem, VContextmenuDivider, VContextmenuSubmenu, and VContextmenuGroup) globally.

import { createApp } from 'vue';
import VContextmenu from 'v-contextmenu';

const app = createApp(App);

// Register the plugin
app.use(VContextmenu);

app.mount('#app');

The v-contextmenu:ref directive allows you to link a target element to a VContextmenu instance. The directive expects the ref to point to a VContextmenu component instance.

You can also pass configuration parameters to the directive to specify which events trigger the menu.

<v-contextmenu ref="contextmenu">
  <v-contextmenu-item>Menu Item</v-contextmenu-item>
</v-contextmenu>

<!-- Basic usage: triggers on contextmenu event -->
<div v-contextmenu:contextmenu></div>

<!-- Advanced usage: triggers on both contextmenu and click events -->
<div v-contextmenu:contextmenu="{ trigger: ['contextmenu', 'click'] }"></div>

The VContextmenuSubmenu component allows for nested menu structures. It can be nested multiple times.

Attributes:

• title (String): The name of the submenu.
• disabled (Boolean): Disables the submenu. Defaults to false.

Slots:

• title: Allows customizing the submenu title via a slot (alternative to the title attribute).

Events:

• mouseenter: Emitted when the mouse enters the submenu.
• mouseleave: Emitted when the mouse leaves the submenu.

<v-contextmenu-submenu title="Submenu Name">
  <v-contextmenu-item>Nested Item</v-contextmenu-item>
</v-contextmenu-submenu>

The VContextmenuItem represents a single clickable entry in the menu. It can only be used inside VContextmenu, VContextmenuSubmenu, or VContextmenuGroup.

Attributes:

• disabled (boolean): Disables the item. Defaults to false.
• hideOnClick (boolean): If true, the menu automatically hides after the item is clicked. Defaults to true.
• contextmenuAsClick (boolean): If true, treats the contextmenu event as a click. Defaults to true.

Events:

• click: Emitted when the item is clicked (provides event).
• contextmenu: Emitted on contextmenu event (provides event).
• mouseenter: Emitted when the mouse enters the item area.
• mouseleave: Emitted when the mouse leaves the item area.

<v-contextmenu-item @click="handleAction">Action</v-contextmenu-item>

The VContextmenuGroup component is used to organize VContextmenuItem components into logical groups with a header.

Attributes:

• title (String): The title for the group.
• maxWidth (Number | String): Sets the maximum width for the group.

Slots:

• title: Allows customizing the group title via a slot (alternative to the title attribute).

<v-contextmenu-group title="Group Title">
  <v-contextmenu-item>Item 1</v-contextmenu-item>
  <v-contextmenu-item>Item 2</v-contextmenu-item>
</v-contextmenu-group>

When manually triggering the visibility of a context menu, you can use the ShowOptions interface to control its placement. This is useful when you need to specify exact coordinates or control automatic adjustment.

Properties:

• top: The vertical position of the menu.
• left: The horizontal position of the menu.
• autoAdjustPlacement: A boolean indicating whether the menu should automatically adjust its position to stay within the viewport.

When adding a reference to the context menu programmatically, you can use AddReferenceOptions to define how that reference is triggered.

Properties:

• trigger: Accepts a TriggerEventTypeOption, which can be a single event type ('contextmenu' or 'click') or an array of these types.

When using the v-contextmenu directive, you can pass an options object to specify which events should trigger the context menu. The trigger option accepts a single event type or an array of event types.

Supported trigger event types are:

• 'contextmenu'
• 'click'

// Example usage in a Vue template
// Trigger on both right-click and left-click
<div v-contextmenu='{ trigger: ["contextmenu", "click"] }'>
  Right click or left click me
</div>

The library exports several components for building structured context menus. When installed via the plugin, these are available globally:

• Contextmenu: The root container for the menu.
• ContextmenuItem: An individual clickable item within the menu.
• ContextmenuDivider: A visual separator between items or groups.
• ContextmenuSubmenu: A menu item that opens a nested submenu.
• ContextmenuGroup: A logical grouping of menu items.

<template>
  <VContextmenu>
    <VContextmenuItem @click="doSomething">Action 1</VContextmenuItem>
    <VContextmenuDivider />
    <VContextmenuGroup>
      <VContextmenuItem>Group Item</VContextmenuItem>
    </VContextmenuGroup>
    <VContextmenuSubmenu title="More">
      <VContextmenuItem>Sub Item</VContextmenuItem>
    </VContextmenuSubmenu>
  </VContextmenu>
</template>

The library provides a contextmenu directive that can be applied to elements to trigger the context menu. This is registered via the install function.

<!-- Example usage of the directive -->
<div v-contextmenu>
  Right click me!
</div>