Column actions

Cell-content components — like TextColumn and DateColumn — that you drop into a column’s cell. They render the cell’s data followed by a chevron-down affordance; clicking opens a menu, a popover, or a value picker anchored to that cell. Use them for in-place row actions (“change this row’s priority”) or in-place detail (“show this cell’s breakdown”).

This is distinct from buildActionsColumn — the trailing ”…” column of row-wide actions. Column actions live inside the data cell they act on.

Component	What it does
`ColumnActionSelect`	Composed — choose one value from a list (status, priority, assignment)
`ColumnActionMenu`	Primitive — content + chevron that opens a dropdown menu
`ColumnActionPopover`	Primitive — content + chevron that opens a popover
`ColumnActionTrigger`	The shared content + chevron trigger, for custom compositions

ColumnActionSelect is built on ColumnActionMenu, which (with ColumnActionPopover) is built on ColumnActionTrigger — itself the table flavor of DisclosureButton (cell-padding alignment + a chevron that stays faint until the row is hovered). Reach for the highest level that fits, drop down when you need more control, and use DisclosureButton directly outside of tables.

Opening a column action never fires onRowClick / row navigation — the DataTable auto-isolates clicks on interactive cell content, so no opt-in is needed. Pair with cellProps: { padding: 'none' } so the cell’s full height is the click target (same as DateColumn).

Choosing a value — `ColumnActionSelect`

The most common column action is “change this row’s status / priority / assignment.” ColumnActionSelect is the composed component for exactly that: pass options, value, and onValueChange, and it derives the trigger from the selected option, builds the radio-group menu (the current value carries the check), and handles the unset state — no per-row conditional logic in your column definition.

In the demo, the Priority column is a ColumnActionSelect; the Units column is a ColumnActionPopover (see below).

Task

Status

Priority

Units

Restock pallet A-12

Open

Cycle count zone 3

Open

Sweep staging lane

Open

Receive PO-9981

Open

import { useState } from "react";
import {
  Badge,
  cn,
  ColumnActionPopover,
  ColumnActionSelect,
  type ColumnActionSelectOption,
  DataTable,
  type DataTableColumn,
  TextColumn,
} from "@vesyl/ui-next";

type Priority = "P0" | "P1" | "P2" | "none";

type Sku = { code: string; qty: number };

type Task = {
  id: string;
  title: string;
  priority: Priority;
  units: number;
  skus: Sku[];
};

function PriorityDot({ palette }: { palette?: "red" | "yellow" | "gray" }) {
  if (!palette) {
    return (
      <span className="size-2 shrink-0 rounded-full border border-muted-foreground/50" />
    );
  }
  return (
    <span
      className={cn(
        "size-2 shrink-0 rounded-full",
        palette === "red" && "bg-red-500",
        palette === "yellow" && "bg-yellow-500",
        palette === "gray" && "bg-gray-400",
      )}
    />
  );
}

// Domain config lives in data, not in the column renderer. A real app would
// pull this into a `PriorityColumnAction` wrapper over `ColumnActionSelect`.
const PRIORITY_OPTIONS: ColumnActionSelectOption<Priority>[] = [
  { value: "P0", label: "P0", hint: "Urgent", indicator: <PriorityDot palette="red" /> },
  { value: "P1", label: "P1", hint: "Medium", indicator: <PriorityDot palette="yellow" /> },
  { value: "P2", label: "P2", hint: "Low", indicator: <PriorityDot palette="gray" /> },
  { value: "none", label: "No priority", indicator: <PriorityDot /> },
];

const initialTasks: Task[] = [
  {
    id: "1",
    title: "Restock pallet A-12",
    priority: "P1",
    units: 12,
    skus: [
      { code: "SKU-1001", qty: 4 },
      { code: "SKU-1002", qty: 2 },
      { code: "SKU-1010", qty: 1 },
      { code: "SKU-1044", qty: 3 },
      { code: "SKU-2087", qty: 1 },
      { code: "SKU-3120", qty: 1 },
    ],
  },
  {
    id: "2",
    title: "Cycle count zone 3",
    priority: "P0",
    units: 48,
    skus: [
      { code: "SKU-4410", qty: 20 },
      { code: "SKU-4411", qty: 18 },
      { code: "SKU-4412", qty: 10 },
    ],
  },
  {
    id: "3",
    title: "Sweep staging lane",
    priority: "none",
    units: 6,
    skus: [
      { code: "SKU-5500", qty: 3 },
      { code: "SKU-5501", qty: 3 },
    ],
  },
  {
    id: "4",
    title: "Receive PO-9981",
    priority: "none",
    units: 30,
    skus: [
      { code: "SKU-7001", qty: 12 },
      { code: "SKU-7002", qty: 9 },
      { code: "SKU-7003", qty: 6 },
      { code: "SKU-7004", qty: 3 },
    ],
  },
];

export default function DataTableColumnAction() {
  const [tasks, setTasks] = useState(initialTasks);

  const setPriority = (id: string, priority: Priority) =>
    setTasks((prev) => prev.map((t) => (t.id === id ? { ...t, priority } : t)));

  const columns: DataTableColumn<Task>[] = [
    {
      id: "title",
      header: "Task",
      width: "fill",
      cell: (t) => <TextColumn fontWeight="medium">{t.title}</TextColumn>,
    },
    {
      id: "status",
      header: "Status",
      width: "sm",
      cell: () => (
        <Badge variant="subtle" colorPalette="yellow">
          Open
        </Badge>
      ),
    },
    {
      id: "priority",
      header: "Priority",
      width: "sm",
      cellProps: { padding: "none" },
      cell: (t) => (
        <ColumnActionSelect
          options={PRIORITY_OPTIONS}
          value={t.priority}
          onValueChange={(value) => setPriority(t.id, value)}
          emptyValue="none"
          placeholder="P?"
          ariaLabel={`Priority for ${t.title}`}
        />
      ),
    },
    {
      id: "units",
      header: "Units",
      width: "sm",
      cellProps: { align: "right", padding: "none" },
      cell: (t) => (
        <ColumnActionPopover
          ariaLabel={`SKU breakdown for ${t.title}`}
          align="end"
          contentClassName="w-56 gap-0 p-2"
          label={
            <span className="flex flex-col items-end leading-tight">
              <span className="text-sm">{t.units} units</span>
              <span className="text-muted-foreground text-xs">
                {t.skus.length} SKUs
              </span>
            </span>
          }
        >
          <p className="px-2 pb-1.5 text-xs font-medium text-muted-foreground">
            {t.units} units across {t.skus.length} SKUs
          </p>
          <ul className="flex flex-col">
            {t.skus.map((sku) => (
              <li
                key={sku.code}
                className="flex items-center justify-between gap-4 rounded-lg px-2 py-1.5 text-sm"
              >
                <span className="font-mono text-xs">{sku.code}</span>
                <span className="tabular-nums text-muted-foreground">
                  {sku.qty}
                </span>
              </li>
            ))}
          </ul>
        </ColumnActionPopover>
      ),
    },
  ];

  return <DataTable data={tasks} columns={columns} getRowId={(t) => t.id} />;
}

import {
  ColumnActionSelect,
  type ColumnActionSelectOption,
} from "@vesyl/ui-next";

const PRIORITY_OPTIONS: ColumnActionSelectOption<Priority>[] = [
  { value: "P0", label: "P0", hint: "Urgent", indicator: <Dot palette="red" /> },
  { value: "P1", label: "P1", hint: "Medium", indicator: <Dot palette="yellow" /> },
  { value: "P2", label: "P2", hint: "Low", indicator: <Dot palette="gray" /> },
  { value: "none", label: "No priority", indicator: <Dot /> },
];

{
  id: "priority",
  header: "Priority",
  width: "sm",
  cellProps: { padding: "none" },
  cell: (task) => (
    <ColumnActionSelect
      options={PRIORITY_OPTIONS}
      value={task.priority}
      onValueChange={(value) => setPriority(task.id, value)}
      emptyValue="none"
      placeholder="P?"
    />
  ),
}

Each option carries its label, an optional hint (the muted secondary text shown only in the menu), and an optional indicator (a leading node — here a colored dot — shown in both the trigger and the menu item).

emptyValue marks the “unset” option: it renders last in the menu under a separator, and when it’s the current value the trigger shows placeholder and stays hidden until the row is hovered (the hideUntilHover behavior, applied for you). Selected values show their label with the default faint chevron — so every select in a table reads consistently.

For a fixed vocabulary, wrap it once so call sites stay terse:

// In your app (the vocabulary is domain-specific, so this lives outside ui-next):
function PriorityColumnAction(props: { value: Priority; onValueChange: (v: Priority) => void }) {
  return <ColumnActionSelect options={PRIORITY_OPTIONS} emptyValue="none" placeholder="P?" {...props} />;
}

// Column definition collapses to one line:
cell: (task) => (
  <PriorityColumnAction value={task.priority} onValueChange={(v) => setPriority(task.id, v)} />
),

Primitives

When the cell isn’t a plain select — free-form popover content, a bespoke menu, or a conditional affordance — drop to the primitives. Both share ColumnActionTrigger (the content + chevron) and differ only in what opens.

Menu — `ColumnActionMenu`

label is the cell content shown in the trigger; children is the menu body. For a single-select mutation use a DropdownMenuRadioGroup (this is what ColumnActionSelect does under the hood); for an action list use DropdownMenuItems.

import { ColumnActionMenu, DropdownMenuItem } from "@vesyl/ui-next";

cell: (row) => (
  <ColumnActionMenu ariaLabel={`Actions for ${row.name}`} label={row.name}>
    <DropdownMenuItem onClick={() => edit(row)}>Edit</DropdownMenuItem>
    <DropdownMenuItem onClick={() => duplicate(row)}>Duplicate</DropdownMenuItem>
    <DropdownMenuItem variant="destructive" onClick={() => remove(row)}>
      Delete
    </DropdownMenuItem>
  </ColumnActionMenu>
),

Detail — `ColumnActionPopover`

Same label, but children is free-form popover content. The default surface is roomy (w-72 p-4) for rich detail; pass contentClassName to tighten it for compact lists. The Units column in the overview demo uses a popover for its SKU breakdown.

import { ColumnActionPopover } from "@vesyl/ui-next";

cell: (task) => (
  <ColumnActionPopover
    ariaLabel={`SKU breakdown for ${task.title}`}
    align="end"
    contentClassName="w-56 gap-0 p-2"
    label={<UnitsLabel units={task.units} skus={task.skus.length} />}
  >
    <SkuBreakdown skus={task.skus} />
  </ColumnActionPopover>
),

Resting state

By default the chevron is faint at rest and sharpens to full strength on row hover or keyboard focus — driven by the group/dt-row the DataTable puts on every row. The cell’s value always stays visible; only the affordance is quieted. No configuration needed.

For empty or optional cells, pass hideUntilHover to hide the whole trigger (value and chevron) until the row is hovered or focused:

State	At rest	On row hover / focus
Default	Content + faint chevron	Chevron reaches full strength
`hideUntilHover`	Nothing (trigger hidden)	Trigger fades in

Reserve hideUntilHover for cells where nothing of value is concealed — there is no hover on touch devices, so it suits the empty state (e.g. an unset priority) rather than real data. The default faint chevron is safe everywhere. Both reveal on focus-within so keyboard users can reach the action, both keep the trigger visible while its popup is open, and both use opacity (not display) so the column never shifts when the trigger appears.

Tuning the faint level: it’s one token in one file — web/ui-next/src/components/data-table/columns/column-action.tsx.

Hover each row. By default the chevron is faint and sharpens on row hover or keyboard focus; hideUntilHover hides the whole trigger until then — for empty or optional cells.

Behavior

Action

Default

Faint chevron at rest; sharpens on row hover

Hover only

hideUntilHover — whole trigger hidden until row hover

import {
  ColumnActionMenu,
  DataTable,
  type DataTableColumn,
  DropdownMenuItem,
  TextColumn,
} from "@vesyl/ui-next";

type Row = {
  id: string;
  hideUntilHover: boolean;
  label: string;
  note: string;
};

const rows: Row[] = [
  {
    id: "1",
    hideUntilHover: false,
    label: "Default",
    note: "Faint chevron at rest; sharpens on row hover",
  },
  {
    id: "2",
    hideUntilHover: true,
    label: "Hover only",
    note: "hideUntilHover — whole trigger hidden until row hover",
  },
];

const columns: DataTableColumn<Row>[] = [
  {
    id: "label",
    header: "",
    width: "sm",
    cell: (r) => <TextColumn fontWeight="medium">{r.label}</TextColumn>,
  },
  {
    id: "note",
    header: "Behavior",
    width: "fill",
    cell: (r) => <TextColumn>{r.note}</TextColumn>,
  },
  {
    id: "action",
    header: "Action",
    width: "sm",
    cellProps: { padding: "none" },
    cell: (r) => (
      <ColumnActionMenu
        hideUntilHover={r.hideUntilHover}
        ariaLabel={`${r.label} actions`}
        label={r.label}
      >
        <DropdownMenuItem>Edit</DropdownMenuItem>
        <DropdownMenuItem>Duplicate</DropdownMenuItem>
        <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
      </ColumnActionMenu>
    ),
  },
];

export default function DataTableColumnActionReveal() {
  return (
    <div className="space-y-3">
      <p className="text-muted-foreground text-sm">
        Hover each row. By default the chevron is faint and sharpens on row
        hover or keyboard focus; <code>hideUntilHover</code> hides the whole
        trigger until then — for empty or optional cells.
      </p>
      <DataTable data={rows} columns={columns} getRowId={(r) => r.id} />
    </div>
  );
}

Custom compositions — `ColumnActionTrigger`

ColumnActionTrigger is exported on its own so you can build the affordance into any base-ui trigger, or render it conditionally. It spreads base-ui trigger props (including data-popup-open, which drives the chevron rotation), so drop it into a render prop:

import { ColumnActionTrigger } from "@vesyl/ui-next";

<PopoverTrigger
  render={(props) => (
    <ColumnActionTrigger {...props}>{label}</ColumnActionTrigger>
  )}
/>;

A common case: collapse an overflow list into a popover only when it’s long enough to need one, and render inline otherwise. The demo renders tags inline when there are two or fewer, and collapses to a ColumnActionPopover (first tag + +N) past that — same chevron affordance, conditional shape.

Reference

ColumnActionSelect

Composed single-select cell. Render inside a column’s cell; pair with cellProps: { padding: 'none' }.

Prop	Type	Default	Description
`options`	`ColumnActionSelectOption<V>[]`	—	Selectable options
`value`	`V`	—	Current value
`onValueChange`	`(value: V) => void`	—	Fired when an option is chosen
`emptyValue`	`V`	—	Option treated as “unset” — hides the trigger until row hover (`hideUntilHover`), shows `placeholder`, renders last under a separator
`placeholder`	`ReactNode`	empty option’s label	Trigger content when `value === emptyValue`
`ariaLabel`	`string`	—	Accessible name for the trigger
`align`	`'start' \| 'center' \| 'end'`	`'start'`	Menu alignment against the trigger
`side`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'bottom'`	Menu side
`disabled`	`boolean`	`false`	Disable the trigger
`triggerClassName`	`string`	—	Class applied to the trigger element
`contentClassName`	`string`	—	Class applied to the menu content surface

ColumnActionSelectOption

Field	Type	Description
`value`	`V`	Option value (the generic `V`)
`label`	`ReactNode`	Trigger content when selected, and the menu item’s primary text
`hint`	`ReactNode`	Secondary muted text in the menu item only
`indicator`	`ReactNode`	Leading node in both the trigger and the menu item (e.g. a dot)

ColumnActionMenu

Interactive cell that opens a dropdown menu.

Prop	Type	Default	Description
`label`	`ReactNode`	—	Visible cell content rendered in the trigger, left of the chevron
`children`	`ReactNode`	—	Menu body — `DropdownMenuItem` / `DropdownMenuRadioGroup` / etc.
`ariaLabel`	`string`	—	Accessible name for the trigger button
`align`	`'start' \| 'center' \| 'end'`	`'start'`	Menu alignment against the trigger
`side`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'bottom'`	Menu side
`alignOffset`	`number`	`0`	Offset along the align axis
`sideOffset`	`number`	`4`	Gap between trigger and menu
`open`	`boolean`	—	Controlled open state
`defaultOpen`	`boolean`	—	Uncontrolled initial open state
`onOpenChange`	`(open: boolean, ...) => void`	—	Open-state change handler
`disabled`	`boolean`	`false`	Disable the trigger
`hideUntilHover`	`boolean`	`false`	Hide the whole trigger until row hover/focus — for empty/optional cells. See Resting state
`triggerClassName`	`string`	—	Class applied to the trigger element
`contentClassName`	`string`	—	Class applied to the menu content surface

ColumnActionPopover

Interactive cell that opens a popover. Same trigger API as ColumnActionMenu; children is free-form popover content.

Prop	Type	Default	Description
`label`	`ReactNode`	—	Visible cell content rendered in the trigger, left of the chevron
`children`	`ReactNode`	—	Popover body — free-form content
`ariaLabel`	`string`	—	Accessible name for the trigger button
`align`	`'start' \| 'center' \| 'end'`	`'start'`	Popover alignment against the trigger
`side`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'bottom'`	Popover side
`alignOffset`	`number`	`0`	Offset along the align axis
`sideOffset`	`number`	`4`	Gap between trigger and popover
`open` / `defaultOpen` / `onOpenChange`	—	—	Open-state passthrough to the popover root
`disabled`	`boolean`	`false`	Disable the trigger
`hideUntilHover`	`boolean`	`false`	Hide the whole trigger until row hover/focus — for empty/optional cells. See Resting state
`triggerClassName`	`string`	—	Class applied to the trigger element
`contentClassName`	`string`	—	Class applied to the popover surface (default `w-72 p-4` — override for compact lists)

ColumnActionTrigger

The shared content + chevron trigger. Extends native <button> props (spread base-ui trigger props onto it via render).

Prop	Type	Default	Description
`children`	`ReactNode`	—	Cell content rendered left of the chevron
`icon`	`ReactNode`	—	Replace the chevron with custom indicator content
`hideUntilHover`	`boolean`	`false`	Hide the whole trigger until row hover/focus
`…`	`button` props	—	Forwarded to the underlying `<button>` (incl. `ref`, `onClick`)

Column actions

Choosing a value — ColumnActionSelect

Primitives

Menu — ColumnActionMenu

Detail — ColumnActionPopover

Resting state

Custom compositions — ColumnActionTrigger

Reference

ColumnActionSelect

ColumnActionSelectOption

ColumnActionMenu

ColumnActionPopover

ColumnActionTrigger

Choosing a value — `ColumnActionSelect`

Menu — `ColumnActionMenu`

Detail — `ColumnActionPopover`

Custom compositions — `ColumnActionTrigger`