gridcn2.0.0
Rows, pages, and menus

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.

Name
Email
Role
Score
Silent Tiger
user0@example.com
Viewer
4
Quick Lion
user1@example.com
Viewer
89
Swift Wolf
user2@example.com
Manager
80
Eager Lion
user3@example.com
User
51
Eager Tiger
user4@example.com
Viewer
83
Silent Wolf
user5@example.com
User
15
Swift Lion
user6@example.com
Viewer
62
Eager Lion
user7@example.com
Manager
42
Eager Eagle
user8@example.com
Editor
35
Bold Tiger
user9@example.com
Editor
52
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: false shows 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: false does 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:

  1. Cut, Copy, and Paste. They use the clipboard pipeline.
  2. Clear contents. It empties the selection to the clearValue() of each cell type.
  3. Insert row above and Insert row below, anchored at the clicked row. They need createRow.
  4. Duplicate rows. It needs duplicateRow.
  5. Delete rows, a destructive item. It runs onBeforeDeleteRows first.

These rules gate the row items:

  • Without createRow or duplicateRow, the menu hides the matching items.
  • A readOnly grid 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, or rowActionAllMatching.

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:

PropTypeDefault
classNamestringnone
childrenReactNodenone
getCellMenuItemsCellMenuItemsResolverbuilt-in cell items
getHeaderMenuItemsHeaderMenuItemsResolverbuilt-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.

On this page