Context menu
Add a header dropdown and right-click menus for sort, pin, hide, clipboard, and row operations, and change the items of each menu.
Users expect a right-click on a cell to offer copy, paste, and row actions. They expect a column header to offer sort and pin. data-grid-context-menu adds two surfaces. The first is a header dropdown, which a right-click on a header also opens. The second is a right-click menu on cells. Both menus are lists of items that you can filter, extend, or replace.
Right-click a cell for cut/copy/paste/clear and row operations; right-click a header (or hover it for the ghost chevron) for sort/pin/hide/autosize.
pnpm dlx shadcn@latest add @gridcn/data-grid-context-menu
DataGridContextMenu wraps DataGridRoot and handles the right-click. DataGridHeaderDropdown renders through the renderHeaderMenu prop of the root:
import {
DataGridBody,
DataGridHeader,
DataGridProvider,
DataGridRoot,
defineColumns,
} from "@/components/data-grid/data-grid";
import {
DataGridContextMenu,
DataGridHeaderDropdown,
} from "@/components/data-grid-context-menu/data-grid-context-menu";
type Row = { id: string; name: string };
const columns = defineColumns<Row>()([
{ id: "name", header: "Name", accessorKey: "name" },
]);
const rows: Row[] = [{ id: "1", name: "Ada" }];
function MyGrid() {
return (
<DataGridProvider defaultData={rows} columns={columns}>
<DataGridContextMenu>
<DataGridRoot
renderHeaderMenu={(ctx) => <DataGridHeaderDropdown {...ctx} />}
>
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridContextMenu>
</DataGridProvider>
);
}DataGridContextMenu belongs inside DataGridProvider.
Header surface
The header dropdown and the right-click header menu show the same items:
- Sort ascending and Sort descending. A column with
sortable: falseshows neither, and no sort group. - Pin to start and Pin to end. If the column cannot pin, they stay but turn off.
- Clear sort, only for a sorted column. Unpin, only for a pinned column.
- Hide column. A column with
hideable: falsedoes not show it. - Move toward start and Move toward end, only while column reorder is on and the column is reorderable. Each one turns off when no neighbor takes the move.
- Widen column, Narrow column, Autosize column, and Autosize all columns, only while column resize is on and the column is resizable.
Column order and pinning owns the pin behavior.
Shift+Alt+ArrowDown (the openColumnMenu action) opens the dropdown of the focused header button's column, or else the active cell's column. Arrow keys move through the items. Escape closes the menu and returns focus to where it was.
Cell surface items
A right-click on a cell outside the selection selects that cell first. A right-click inside the selection keeps it. The row items act on every view row that the selection covers, or on the clicked row if nothing is selected. With a checkedRowsLifetime of 'until-cleared' or 'across-filters' and a checked row, they act on the checked rows only. With 'until-click' (the default without a checkbox marker or totalRowCount), a right-click outside the selection ends the checks. Set 'until-cleared' to keep them for bulk menu actions.
Shift+F10 opens the cell menu of the active cell on Windows and Linux. The browser sends it as a right-click.
The cell menu holds these items, in order:
- Cut, Copy, and Paste. They use the clipboard pipeline.
- Clear contents. It empties the selection to the
clearValue()of each cell type. - Insert row above and Insert row below, anchored at the clicked row. They need
createRow. - Duplicate rows. It needs
duplicateRow. - Delete rows, a destructive item. It runs
onBeforeDeleteRowsfirst.
These rules gate the row items:
- Without
createRoworduplicateRow, the menu hides the matching items. - A
readOnlygrid turns off every item except Copy. - Duplicate and Delete turn off while all matching is on, and with
checkedRowsLifetime="across-filters"when every checked row is hidden. The insert items stay on, because they insert next to the right-clicked row. - A turned-off row item shows the reason as its tooltip:
labels.contextMenu.rowActionReadOnly,rowActionHiddenChecked, orrowActionAllMatching.
An item that has a keymap action shows its key as a hint. The fill and header items show none. Row operations owns what each operation does.
If a Cut or Copy write fails, the next menu opens with both items turned off and the labels.contextMenu.clipboardFailed tooltip.
Row markers, the empty space below the last row, the scrollbar gutter, pinned rows, and unloaded rows have no menu. A right-click on them opens the browser menu.
Custom menu items
Each surface resolves its items through a function prop of DataGridContextMenu. The function receives the built-in items as defaults and returns the complete list. Return defaults unchanged, filter it, reorder it, extend it, or build a new list:
| Prop | Type | Default |
|---|---|---|
className | string | none |
children | ReactNode | none |
getCellMenuItems | CellMenuItemsResolver | built-in cell items |
getHeaderMenuItems | HeaderMenuItemsResolver | built-in header items |
getCellMenuItems(ctx, defaults) receives ctx with rowId, viewRowIndex, columnId, canInsertRow, and canDuplicateRow of the clicked cell. ctx.targetRowIds lists the row ids that the row items act on, and ctx.actions holds the grid actions. getHeaderMenuItems(ctx, defaults) receives columnId, scrollRoot, the scroll container element, and actions. If the clicked element has no grid ancestor, scrollRoot is null. The header resolver applies to the right-click header menu and to every DataGridHeaderDropdown inside the wrapper.
Built-in items have stable ids, so a resolver can keep or drop them by id. Context menu options lists every id.
The fill items exist only for a touch selection while the fill add-on runs. An item is an object with id, label, icon, shortcut, disabled, destructive, tooltip, and onClick. shortcut is a keymap binding that the menu shows as keycaps. tooltip shows on hover while the item is off. A separator is { id, separator: true }. The types are GridMenuItemSpec, CellMenuItemsResolver, and HeaderMenuItemsResolver.
This menu keeps two row items for cells and one sort item for headers. Render it inside DataGridProvider:
import {
DataGridBody,
DataGridHeader,
DataGridRoot,
} from "@/components/data-grid/data-grid";
import { DataGridContextMenu } from "@/components/data-grid-context-menu/data-grid-context-menu";
const KEEP_CELL = new Set(["insert-row-below", "duplicate-rows"]);
function FilteredMenus() {
return (
<DataGridContextMenu
getCellMenuItems={(_ctx, defaults) =>
defaults.filter((item) => KEEP_CELL.has(item.id))
}
getHeaderMenuItems={(_ctx, defaults) =>
defaults.filter((item) => item.id === "sort-asc")
}
>
<DataGridRoot>
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridContextMenu>
);
}This menu adds a Copy row id item, which the built-in menu lacks. Render the component inside DataGridProvider:
import { Copy } from "lucide-react";
import {
DataGridBody,
DataGridHeader,
DataGridRoot,
} from "@/components/data-grid/data-grid";
import { DataGridContextMenu } from "@/components/data-grid-context-menu/data-grid-context-menu";
function GridWithExtraItem() {
return (
<DataGridContextMenu
getCellMenuItems={(ctx, defaults) => [
...defaults,
{
id: "copy-row-id",
label: "Copy row id",
icon: <Copy className="size-4 text-muted-foreground" />,
onClick: () => navigator.clipboard.writeText(ctx.rowId),
},
]}
>
<DataGridRoot>
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridContextMenu>
);
}A resolver is a plain function. Read grid state from ctx. Read hook values in your component and use them in the resolver.
Server mode
On a server grid, All matching turns off Duplicate and Delete. A row item on unloaded rows does nothing, with the reason "unloaded-rows". See Row operations.
Touch and paste
Long-press a cell or a header for 500 ms to open its menu. onCellContextMenu fires as it does for a right-click. While the fill add-on runs, the cell menu of a touch selection also lists Fill down and Fill right.
The Paste item reads the system clipboard, which needs the clipboard-read permission. If the browser denies it, the item turns off and shows the labels.contextMenu.pasteBlocked hint.
Labels
Every item text comes from labels.contextMenu, including fillDown and fillRight. See Labels.
Related
- Context menu options: the full option list
- Row operations: the operations behind the row items
- Column order and pinning: the pin behavior the header items control
- Clipboard: the Cut, Copy, and Paste pipeline
- Context menu items example: menus that keep some built-in items
Client pagination
Split a local array into pages with a pager footer, and learn what sort, filter, search, edits, and selection do on a page.
Add comments to cells
Attach comments to cells with the data-grid-comments add-on. Keep them in the browser, or save them through your own server and share them between clients.