Context Menu Plugin

The Context Menu plugin adds a customizable right-click menu to your grid cells. Build anything from simple copy/paste actions to complex nested menus with conditional visibility, icons, and keyboard shortcuts.

Installation

import '@toolbox-web/grid/features/context-menu';

Basic Usage

Define your menu items as an array—each item has an id, label, and action callback that receives context about the clicked cell (row data, column info, cell value, etc.). Add separators between groups of actions for visual clarity.

TypeScript

import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');

function removeRow(rowIndex: number) {
  grid.rows = grid.rows.filter((_, i) => i !== rowIndex);
}

grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'status', header: 'Status' }
  ],
  features: {
    contextMenu: {
      items: [
        { id: 'copy', name: 'Copy Cell', action: (ctx) => navigator.clipboard.writeText(String(ctx.value)) },
        { id: 'sep1', name: '', separator: true },
        { id: 'delete', name: 'Delete Row', action: (ctx) => removeRow(ctx.rowIndex) },
      ],
    },
  },
};

React

import '@toolbox-web/grid-react/features/context-menu';
import { DataGrid } from '@toolbox-web/grid-react';
import type { GridConfig } from '@toolbox-web/grid-react';

function MyGrid({ data, onDelete }) {
  const gridConfig: GridConfig = {
    columns: [
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email' },
      { field: 'status', header: 'Status' }
    ],
    features: {
      contextMenu: {
        items: [
          { id: 'copy', name: 'Copy Cell', action: (ctx) => navigator.clipboard.writeText(String(ctx.value)) },
          { id: 'sep1', name: '', separator: true },
          { id: 'delete', name: 'Delete Row', action: (ctx) => onDelete(ctx.rowIndex) },
        ],
      },
    },
  };

  return <DataGrid rows={data} gridConfig={gridConfig} style={{ height: '400px' }} />;
}

Alternative: feature prop

You can instead pass columns={[ … ]} and contextMenu={{ … }} as individual props on <DataGrid>. That form is idiomatic React, but gridConfig keeps the configuration identical across every framework.

Vue

<script setup>
import '@toolbox-web/grid-vue/features/context-menu';
import { TbwGrid } from '@toolbox-web/grid-vue';
import type { GridConfig } from '@toolbox-web/grid-vue';

const data = [
  { name: 'Alice', email: 'alice@example.com', status: 'active' },
  { name: 'Bob', email: 'bob@example.com', status: 'inactive' },
];

const gridConfig: GridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'status', header: 'Status' },
  ],
  features: {
    contextMenu: {
      items: [
        { id: 'copy', name: 'Copy Cell', action: (ctx) => navigator.clipboard.writeText(String(ctx.value)) },
        { id: 'sep1', name: '', separator: true },
        { id: 'delete', name: 'Delete Row', action: (ctx) => console.log('Delete row:', ctx.rowIndex) },
      ],
    },
  },
};
</script>

<template>
  <TbwGrid :rows="data" :grid-config="gridConfig" style="height: 400px" />
</template>

Alternative: prop + light-dom columns

You can instead bind :context-menu="{ … }" and declare columns with <TbwGridColumn> children. That form is idiomatic Vue, but gridConfig keeps the configuration identical across every framework.

Angular

import '@toolbox-web/grid-angular/features/context-menu';
import { Component, output } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { GridConfig } from '@toolbox-web/grid-angular';
import type { ContextMenuItem } from '@toolbox-web/grid/plugins/context-menu';

@Component({
  selector: 'app-my-grid',
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="rows"
      [gridConfig]="gridConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  deleteRow = output<number>();
  rows = [...];

  gridConfig: GridConfig = {
    columns: [
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email' },
      { field: 'status', header: 'Status' }
    ],
    features: {
      contextMenu: {
        items: [
          { id: 'copy', name: 'Copy Cell', action: (ctx: any) => navigator.clipboard.writeText(String(ctx.value)) },
          { id: 'sep1', name: '', separator: true },
          { id: 'delete', name: 'Delete Row', action: (ctx: any) => this.deleteRow.emit(ctx.rowIndex) },
        ] as ContextMenuItem[],
      },
    },
  };
}

Alternative: per-feature directive

You can instead import GridContextMenuDirective and bind [contextMenu] directly on <tbw-grid>. That form gives a compile-time check that the feature is imported, but gridConfig.features above is the recommended, framework-consistent approach.

Demos

Default Context Menu

Show source

Right-click any cell to see the context menu.

With Submenus

Show source

Nested menu items for complex actions.

Conditional Items

Show source

Show/hide items based on context.

Grouped Menu

Show source

Label each section of the menu with what it acts on. Right-click a single row, then Ctrl/⌘-click to select several rows and right-click again — the selected rows group appears only when it has items. See Group Headers.

Plugin-Contributed Items

Right-click any cell to see the context menu. Items from FilteringPlugin, VisibilityPlugin, and PinnedColumnsPlugin are automatically contributed alongside custom items.

Show source

Plugins like FilteringPlugin, VisibilityPlugin, and PinnedColumnsPlugin can contribute their own items to the context menu automatically.

Configuration Options

Option	Type	Default	Description
items	ContextMenuItem[]	Copy + Export CSV	Menu items to display

TypeScript Interfaces

• ContextMenuItem — Menu item definition (id, label, icon, action, submenus, etc.)
• ContextMenuParams — Context passed to action callbacks (row, column, value, selection, etc.)
• ContextMenuConfig — Plugin configuration options

Selection Sync

When used with the SelectionPlugin, the context menu reports the selection in params.selectedRows and syncs it to the cell the menu was opened on. Every way of opening the menu syncs identically — right-click, touch long-press, Shift + F10, the ☰ Menu key, or a synthesised contextmenu — so keyboard, touch, and assistive-technology users act on exactly the selection a mouse user would.

Opened on…	Behavior
A selected row (row mode)	Multi-selection preserved; selectedRows = all selected rows
An unselected row (row mode)	Selects only that row
A cell inside a range (range mode)	Range preserved; selectedRows = every row the range covers
A cell outside every range (range mode)	Range collapses to that cell; selectedRows = [rowIndex]
Any cell (cell mode)	Cell selection moves to that cell; selectedRows = [rowIndex]
A cell in a selected column (mode: [..., 'column'])	Column selection preserved; selectedRows = [rowIndex]
A cell with no SelectionPlugin loaded	selectedRows = [rowIndex]
A header	selectedRows = []

This uses the plugin query system for loose coupling — no hard dependency on SelectionPlugin.

Conditional Items

features: {
  contextMenu: {
    items: [
      {
        id: 'edit',
        name: 'Edit',
        hidden: (params) => params.column.editable !== true,
      },
      {
        id: 'delete',
        name: 'Delete',
        disabled: (params) => params.row.locked === true,
      },
    ],
  },
},

Group Headers

Menus that mix actions of different scope — the clicked cell, the whole row, a selection of rows — are easier to scan when each section is labelled. Give a separator a label to turn it into a group header: a divider with the label inline.

features: {
  contextMenu: {
    items: (params) => [
      { id: 'cell', name: '', separator: true, label: 'Cell' },
      { id: 'copy', name: 'Copy value', action: (p) => copy(p.value) },
      { id: 'row', name: '', separator: true, label: 'Row' },
      { id: 'edit', name: 'Edit row', action: (p) => edit(p.row) },
      { id: 'rows', name: '', separator: true, label: `${params.selectedRows.length} selected rows` },
      { id: 'delete', name: 'Delete selected', hidden: (p) => p.selectedRows.length < 2, action: (p) => remove(p.selectedRows) },
    ],
  },
},

─ Cell ────────────
  Copy value
─ Row ─────────────
  Edit row

• A plain separator (separator: true without label) still renders a bare divider.
• Group headers are not focusable or clickable and are skipped by the arrow keys.
• Empty groups collapse automatically. When every item after a header is hidden, the header is dropped too — no need to compute hidden for the header yourself. A header may lead the menu (plain separators may not), and a plain separator directly before a header is absorbed by it.
• hidden (static or a function) works on headers like any other item, and headers work inside subMenu as well.

Events

Right-click on cells or headers to open the context menu.

Event Log:Clear

Event	Detail	Description
context-menu-open	{ params, items }	Menu opened

Styling

The context menu supports CSS custom properties for theming. Override these on tbw-grid or a parent container:

CSS Custom Properties

Property	Default	Description
--tbw-context-menu-bg	var(--tbw-color-panel-bg)	Menu background
--tbw-context-menu-fg	var(--tbw-color-fg)	Menu text color
--tbw-context-menu-border	var(--tbw-color-border)	Menu border
--tbw-context-menu-hover	var(--tbw-color-row-hover)	Item hover background
--tbw-context-menu-group-header-fg	var(--tbw-context-menu-muted, var(--tbw-color-fg-muted))	Group header label color
--tbw-context-menu-group-header-size	var(--tbw-font-size-xs)	Group header label size
--tbw-menu-min-width	10rem	Minimum menu width
--tbw-menu-item-padding	0.375rem 0.75rem	Menu item padding
--tbw-menu-item-gap	0.5rem	Gap between icon and label
--tbw-font-size-sm	0.9285em	Menu font size
--tbw-font-size-xs	0.7857em	Shortcut text size
--tbw-icon-size	1em	Icon width

Example

tbw-grid {
  /* Custom context menu styling */
  --tbw-context-menu-bg: #2d2d2d;
  --tbw-context-menu-fg: #ffffff;
  --tbw-context-menu-border: #444444;
  --tbw-context-menu-hover: #3d3d3d;
  --tbw-menu-item-padding: 0.5rem 1rem;
}

CSS Classes

The menu uses these class names for advanced customization:

Class	Element
.tbw-context-menu	Menu container
.tbw-context-menu-item	Menu item row
.tbw-context-menu-item.disabled	Disabled item
.tbw-context-menu-item.danger	Danger/delete action
.tbw-context-menu-icon	Item icon container
.tbw-context-menu-label	Item label text
.tbw-context-menu-shortcut	Keyboard shortcut
.tbw-context-menu-separator	Divider line
.tbw-context-menu-separator.tbw-context-menu-group-header	Group header (labelled divider)
.tbw-context-menu-group-label	Group header label text

Accessibility

The popup follows the WAI-ARIA Menu pattern:

• The popup is role="menu"; items are role="menuitem" (tabindex="-1", focus moved between them by the keyboard), dividers are role="separator", group headers are role="separator" named by aria-label (the visible label), and disabled items carry aria-disabled="true" and are skipped.
• ↑ / ↓ move between items (wrapping), Enter / Space activates, and Esc closes. Clicking outside or scrolling also closes it (see Accessibility guide).

The plugin also respects the keyboard-open path: Shift + F10 and the dedicated ☰ Menu key open the menu at the focused cell with focus moved to the first item, and sync the selection exactly as a right-click on that cell does (see Selection Sync), so the menu is fully operable from the keyboard (SC 2.1.1 Keyboard).

Touch input

On a touch device the menu opens with a long-press, with no extra configuration. This is not a polyfill: browsers already synthesise a native contextmenu event from a long-press, exactly as they do from a right-click, so the same listener serves both.

Because a long-press is an overloaded gesture, the grid resolves it in a fixed order:

You long-press	What opens	When
A header cell	Column header menu	Once the header-menu plugin ships (tracked in #270)
A row	Touch selection mode	SelectionPlugin is registered with mode: 'row'
A cell	Cell range painting	SelectionPlugin is registered with mode: 'cell' or 'range'
A row or cell	This menu	None of the above applies

The grid offers a long-press to its plugins after 400 ms, and only suppresses the browser’s contextmenu if one of them claims it. So this menu needs no opt-in — it opens whenever nothing else wanted the gesture.

Parity when selection mode wins

When SelectionPlugin claims the long-press, these menu items are still one tap away: the selection toolbar’s More… button opens them. That button only appears when ContextMenuPlugin is registered.

See the Touch input guide for the full gesture table.

See Also

• Selection — Row and cell selection
• Editing — Inline cell editing
• Clipboard — Copy/paste cells
• Touch input — Long-press and gesture reference