Grid

The Grid widget displays tabular data with features like fixed headers, single and multiple selection modes, sorting, filtering, grouping, aggregation, rich cell content, tree columns, and more.

<div controller={PageController}>
  <Grid
    records={m.records}
    style="height: 400px"
    scrollable
    columns={[
      { header: "Name", field: "fullName", sortable: true },
      { header: "Continent", field: "continent", sortable: true },
      { header: "Browser", field: "browser", sortable: true },
      { header: "OS", field: "os", sortable: true },
      {
        header: "Visits",
        field: "visits",
        sortable: true,
        align: "right",
      },
    ]}
    selection={{
      type: KeySelection,
      bind: m.selection,
      keyField: "id",
      multiple: true,
    }}
  />
</div>

class PageController extends Controller {
  onInit() {
    this.store.set(
      m.records,
      Array.from({ length: 20 }, (_, i) => ({
        id: i + 1,
        fullName: [
          "John Doe",
          "Jane Smith",
          "Bob Wilson",
          "Alice Brown",
          "Charlie Davis",
        ][i % 5],
        continent: ["Europe", "North America", "Asia", "Africa", "Australia"][
          i % 5
        ],
        browser: ["Chrome", "Firefox", "Safari", "Edge"][i % 4],
        os: ["Windows", "macOS", "Linux", "iOS", "Android"][i % 5],
        visits: Math.floor(Math.random() * 100) + 1,
      })),
    );
  }
}

interface Person {
  id: number;
  fullName: string;
  continent: string;
  browser: string;
  os: string;
  visits: number;
}

interface PageModel {
  records: Person[];
  selection: Record<number, boolean>;
}

const m = createModel<PageModel>();

import { createModel } from "cx/data";
import { Controller, KeySelection } from "cx/ui";
import { Grid } from "cx/widgets";

Click on column headers to sort. Hold Ctrl (or Cmd on macOS) and click to select multiple rows.

Columns

Columns define what data is displayed and how. The simplest column configuration uses the field property to display a record property:

columns={[
  { header: "Name", field: "fullName" },
  { header: "Age", field: "age", align: "right" }
]}

For custom cell content, use the children property to render any widget inside the cell. The current record is available via $record:

columns={[
  {
    header: "Name",
    field: "fullName",
    children: <strong text={m.$record.fullName} />
  },
  {
    header: "Actions",
    children: (
      <Button
        text="Edit"
        onClick={(e, { store }) => {
          edit(store.get(m.$record))
        }}
      />
    )
  }
]}

Use value for computed display values while keeping field for sorting:

{
  header: "Status",
  field: "active",
  value: { expr: "{$record.active} ? 'Yes' : 'No'" }
}

Headers

The header property can be a simple string or a configuration object for advanced scenarios like multi-row headers, custom tools, or spanning columns:

columns={[
  {
    header: {
      text: "Name",
      colSpan: 2,
      align: "center"
    },
    field: "fullName"
  },
  {
    header: {
      text: "Sales",
      tool: <Icon name="drop-down" />,
      allowSorting: false
    },
    field: "sales"
  }
]}

Use colSpan and rowSpan to create complex multi-row headers. The tool property allows adding custom components like filter dropdowns or menus inside the header.

Dynamic Columns

Use columnParams and onGetColumns to dynamically generate columns based on data or user preferences:

<Grid
  records={m.records}
  columnParams={m.visibleColumns}
  onGetColumns={(params) => {
    const baseColumns = [{ header: "Name", field: "name" }];
    const dynamicColumns = params.map((col) => ({
      header: col.label,
      field: col.field,
    }));
    return [...baseColumns, ...dynamicColumns];
  }}
/>

Whenever columnParams changes, onGetColumns is called to recalculate the column configuration. This is useful for user-configurable column visibility, pivot tables, or data-driven column generation.

See also: Complex Headers, Column Resizing, Column Reordering, Fixed Columns, Dynamic Columns

Grouping

Grids support multi-level grouping with aggregates. Define grouping levels using the grouping property:

<Grid
  records={m.records}
  grouping={[
    {
      key: { continent: m.$record.continent },
      showFooter: true,
    },
  ]}
  columns={[
    { header: "Continent", field: "continent" },
    { header: "Name", field: "fullName" },
    {
      header: "Sales",
      field: "sales",
      aggregate: "sum",
      footer: { tpl: "{$group.sales:n;2}" },
    },
  ]}
/>

Each grouping level supports the following options:

Column aggregates (sum, count, avg, distinct) are automatically calculated and available in footer/caption templates via $group.

For dynamic grouping, use groupingParams and onGetGrouping:

<Grid
  records={m.records}
  groupingParams={m.selectedGrouping}
  onGetGrouping={(params) => {
    if (!params) return null;
    return [
      {
        key: { value: m.$record[params.field] },
        showFooter: true,
      },
    ];
  }}
  columns={columns}
/>

Whenever groupingParams changes, onGetGrouping is called to recalculate the grouping configuration. This allows users to change grouping at runtime.

See also: Grouping, Dynamic Grouping

Drag & Drop

Grids support drag and drop for reordering rows, moving data between grids, and column reordering. Configure dragSource and dropZone to enable this functionality:

<Grid
  records={m.records}
  dragSource={{ mode: "move", data: { type: "record" } }}
  dropZone={{ mode: "insertion" }}
  onDrop={(e, { store }) => {
    // Handle the drop - reorder records
    store.update(m.records, (records) => {
      // Move record from e.source.recordIndex to e.target.insertionIndex
    });
  }}
  columns={columns}
/>

The dropZone.mode can be insertion (shows insertion line between rows) or preview (highlights the target row). Use onDropTest to control which drops are allowed.

See also: Row Drag and Drop

Examples

• Searching and Filtering
• Pagination
• Multiple Selection
• Form Edit
• Row Editing
• Cell Editing
• Inline Edit
• Tree Grid
• Stateful TreeGrid
• Header Menu
• Buffering
• Infinite Scrolling
• Row Expanding

Grid Configuration

Data

Selection

Sorting

Grouping

Filtering

Appearance

Performance

Infinite Scrolling

Cell Editing

Focus & Hover

Row Callbacks

Column Callbacks

Other

Column Configuration

Column Header Configuration

When header is an object, the following properties are available:

Drag & Drop Configuration

Drag & Drop Callbacks

onDragStart(e: DragEvent, instance: Instance) - Called when the user starts dragging a row.

• e - The native drag event.
• instance - The grid instance.

onDragEnd(e: DragEvent, instance: Instance) - Called when the user stops dragging.

• e - The native drag event.
• instance - The grid instance.

onDragOver(e: GridDragEvent, instance: Instance): boolean? - Called when the user drags over another item. Return false to prevent dropping.

• e - Grid drag event containing source and target with record indices.
• instance - The grid instance.

onDrop(e: GridDragEvent, instance: Instance) - Called when a drop occurs. Use it to update data such as rearranging the list.

• e - Grid drag event containing source and target with record indices and insertion index.
• instance - The grid instance.

onDropTest(e: DragEvent, instance: Instance): boolean - Checks whether a drop action is allowed. Return false to reject.

• e - The native drag event.
• instance - The grid instance.

onRowDragOver(e: GridRowDragEvent, instance: Instance): boolean? - Called when dragging over a specific row. Useful for tree grids.

• e - Grid row drag event containing source record and target row info.
• instance - The grid instance.

onRowDrop(e: GridRowDragEvent, instance: Instance): boolean? - Called when dropping onto a row. Use it to attach a node to a subtree.

• e - Grid row drag event containing source record and target row info.
• instance - The grid instance.

onRowDropTest(e: DragEvent, instance: Instance): boolean - Checks whether a row drop action is allowed.

• e - The native drag event.
• instance - The grid instance.

onColumnDrop(e: GridColumnDropEvent, instance: Instance): boolean? - Called when a column is dropped. Use it for column reordering.

• e - Column drop event containing column info.
• instance - The grid instance.

onColumnDropTest(e: DragEvent, instance: Instance): boolean - Checks whether a column drop is valid.

• e - The native drag event.
• instance - The grid instance.

onCreateIsRecordDraggable(): (record) => boolean - Returns a predicate function that determines which records can be dragged.