agrid is an Angular data grid with spreadsheet-like editing, virtual scrolling, filtering, sorting, grouping, column state, pinned columns, selection, clipboard workflows, row operations, pagination, CSV/Excel export, charts/graphs, and custom cell renderers.

https://thkl.github.io/agrid/

npm install @thkl/agrid @angular/cdk

import { Component } from '@angular/core';
import { AgridComponent, AgridControl, AgridDataSource, AgridProvider, ColDef, GridEditEvent } from '@thkl/agrid';

const columns: ColDef[] = [
  { field: 'id', header: 'ID', width: 70, editable: false, pinned: 'left' },
  { field: 'name', header: 'Name', width: 160, filterable: true },
  { field: 'hiredAt', header: 'Hire Date', width: 130 }, // auto-formatted as a date
  { field: 'departmentId', header: 'Department', width: 140, filterable: true, groupable: true,
    values: [
      { value: 1, label: 'Engineering' },
      { value: 2, label: 'Sales' },
    ],
  },
];

@Component({
  selector: 'app-page',
  imports: [AgridComponent],
  template: `
    <agrid [provider]="gridProvider" (cellEdit)="onCellEdit($event)" />
  `,
})
export class PageComponent {
  readonly columns = columns;
  readonly ds = new AgridDataSource([
    { id: 1, name: 'Alice', hiredAt: '2021-03-15', departmentId: 1 },
    { id: 2, name: 'Bob',   hiredAt: '2022-07-01', departmentId: 2 },
  ]);
  readonly gridControl = new AgridControl({ allowRowReorder: true });
  readonly gridProvider = new AgridProvider({
    locale: 'en-US',
    columns: this.columns,
    datasource: this.ds,
    control: this.gridControl,
    showControlColumn: true,
    showSidebar: true,
    zebraStripes: true,
    rowSelection: 'multi',
  });

  onCellEdit(event: GridEditEvent): void {
    console.log(event);
  }
}

See ROADMAP.md for the AG Grid comparison checklist and open parity items.

• Angular 21 standalone component.
• CDK virtual scrolling for large row sets.
• Signal-based data source and control state.
• Editable text cells and select editors for fixed value columns.
• Custom component cell editors via ColDef.cellEditor (star ratings, pickers, sliders) with zero extra dependencies.
• Keyboard navigation with auto-scroll to the active cell.
• Type-to-edit, Enter/F2 edit, Tab/Enter commit, Escape cancel.
• Undo/redo for edits, paste, and fill operations.
• Cell range selection with Shift+arrow, Shift+click, or left-button drag with edge auto-scroll.
• Clipboard copy/paste using TSV/CSV-like plain text.
• Live selection status bar with count, sum, average, minimum, and maximum.
• Fill handle for repeating selected cell/range values down or right.
• Find panel with Ctrl/Cmd+F, full filtered-dataset matching, and next/previous navigation.
• Quick filter for searching across all visible columns.
• Text filters, string/number/date condition filters, value filters, and single-column sorting.
• Server-side filter/sort events for remote data workflows.
• Column menu with sort, clear sort, autosize, pin/unpin, hide, group, and clear filter actions.
• Column resizing by drag and autosize by double-click.
• Column reordering by header drag.
• Column virtualization for very wide grids.
• Conditional cell formatting with colors, typography, borders, and alignment.
• Row-aware horizontal cell spanning, clamped within each pinned or scrollable pane.
• Split-pane pinned columns on the left.
• Optional control column for row context actions, row numbers, row marking, and row reordering.
• Column marking for complete-column highlighting and clipboard workflows.
• Row selection: none, single, or multi.
• Grouping with expand/collapse and custom group actions.
• Sidebar column visibility picker.
• Add-row placeholder and automatic row insertion.
• CSV and zero-dependency Excel (.xlsx) export of visible, filtered data rows.
• Server-side row model with lazy block loading and virtual placeholders.
• Date auto-formatting — ISO strings and Date objects are detected and displayed as locale-formatted dates automatically.
• Zebra stripes — alternating row shading for easier reading.
• Readonly mode — disable all editing with a single input.
• Pagination — built-in page controls driven by AgridControl.
• Pivot tables — derive read-only cross-tab views from row, column, value, and aggregate fields.
• Tree node aggregates — roll up sum, average, count, or custom values into expandable tree nodes.
• Custom cell renderers — render any Angular component per column for rich cell content (the legacy HTML-string renderer is deprecated).
• Custom cell editors — render any Angular component while editing; the grid keeps validation, history, and the commit lifecycle.
• Charts / graphs — zero-dependency SVG column/bar/line/area/pie/donut diagrams via <agrid-chart>, configured with an AgridChartProvider. Link to a grid's visibleRows to follow filters and sorting live.
• Sparklines — inline SVG line and bar charts rendered per row from numeric series data.
• Column autosize all — fit every visible column to its content in one call.
• Master/detail rows — expand any row to reveal a custom HTML detail panel beneath it.
• Pinned rows — keep summary/total rows fixed at the top or bottom of the body.
• Persistable settings — save and restore serializable column, filter, sidebar, and pivot state.
• Row CSS classes — apply conditional classes to whole rows via getRowClass.

<agrid [provider]="gridProvider" (cellEdit)="onEdit($event)" />

AgridComponent has a single input: provider. All grid options, data, and control state are supplied through AgridProvider. See AgridProvider Configuration for the full option list.

Set locale on AgridProvider to control built-in grid text and date formatting. Built-in text supports English (en-*) and German (de-*).

The default is 'auto', which reads navigator.language from the browser and falls back to 'en-US' if the browser language is not supported.

// Auto-detect browser language (default — no need to set locale explicitly)
readonly gridProvider = new AgridProvider({ ... });

// Pin to a specific locale
readonly gridProvider = new AgridProvider({ locale: 'de-DE', ... });

Use addLocalization(locale, overrides) to register label overrides for one or more locales. When locale is 'auto', the grid matches the browser language against all registered locales — exact match first, then primary-language match (e.g. a registered 'fr' locale matches a browser locale of 'fr-FR' or 'fr-BE').

readonly gridProvider = new AgridProvider({ ... })
  .addLocalization('fr-FR', {
    addRow: 'Ajouter une ligne',
    noRows: 'Aucune donnée',
    rows: count => `${count} enregistrement${count === 1 ? '' : 's'}`,
    groupBy: header => `Grouper par ${header}`,
  })
  .addLocalization('nl-NL', {
    addRow: 'Rij toevoegen',
    noRows: 'Geen rijen',
  });

addLocalization returns the provider so calls can be chained. Partial overrides are merged on top of the built-in base bundle for that locale — you only need to supply the labels you want to change.

The AgridLocaleTextOverrides type covers all overridable labels.

Use rowChanged instead of cellEdit when an API should receive the complete row only after the user finishes editing it:

<agrid [provider]="provider" (rowChanged)="saveRow($event)" />

saveRow(event: RowUpdateEvent<PersonRow>): void {
  this.http.patch(`/api/people/${event.row.id}`, event.row).subscribe(() => {
    this.provider.control.indicate(event.originalIndex, '#2da44e', 1000);
    this.provider.control.clearChangedCells(event.originalIndex);
  });
}

During inline editing, moving between fields in the same row does not emit rowChanged. The event fires when navigation enters another row, filter focus clears the active cell, or focus leaves the grid. recordEdit and cellEdit continue to fire for each committed field mutation.

Enable changed-cell markers when the user should see which values are waiting to be persisted:

readonly provider = new AgridProvider<PersonRow>({
  columns,
  datasource,
  showChangedCellIndicator: true,
});

After a successful API request, call control.clearChangedCells(index) for the complete row, control.clearChangedCells(index, ['name', 'email']) for selected fields, or control.clearChangedCells() for every marker. Call control.indicate(index, color, durationMs) to flash a complete row for transient server-side feedback.

All grid options are passed to AgridProvider at construction time:

readonly gridProvider = new AgridProvider({
  columns: this.columns,
  datasource: this.ds,
  control: this.gridControl,
  zebraStripes: true,
  showSidebar: true,
  showControlColumn: true,
  rowSelection: 'multi',
  allowAddRows: true,
  enableRowMarking: true,
  confirmRowDelete: true,
  readonly: false,
});

Set aggregateTreeNodes to display aggregate-column values on every expandable tree node. The grid uses each column's existing aggregate function, so footer and tree aggregation share the same sum/average/minimum/maximum/count or custom-function configuration.

const columns: ColDef<OrgRow>[] = [
  { field: 'name', header: 'Name' },
  { field: 'amount', header: 'Amount', type: 'number', aggregate: 'sum' },
];

const treeConfig: AgridTreeConfig<OrgRow> = {
  getId: row => row.id,
  getParentId: row => row.parentId,
  treeField: 'name',
  aggregateTreeNodes: true,
};

Rollups use descendant leaves, not intermediate parent values, which avoids double-counting stored subtotals in multi-level trees. Collapsed descendants continue to contribute. Active filters recalculate rollups over the filtered tree, including ancestors retained by keepAncestorsOnFilter. Parent aggregate cells are display-only and do not overwrite source data. Generated getPath branches use all datasource leaves beneath the branch and show their rollups inline.

AgridTreeComponent and AgridTreeProvider provide the same hierarchy without grid columns. The control accepts AgridTreeConfig<T>, supports keyboard navigation and selection, and emits normalized row/path-branch events. Because the standalone tree has no columns, it ignores aggregateTreeNodes.

readonly treeProvider = new AgridTreeProvider<Node>({
  datasource: new AgridDataSource(nodes),
  treeConfig: {
    getId: node => node.id,
    getParentId: node => node.parentId,
    treeField: 'name',
    defaultExpanded: true,
  },
  getDescription: node => node.type,
});

<agrid-tree [provider]="treeProvider" (nodeClick)="openNode($event)" />

The first pivot slice creates a read-only table from one row dimension, one column dimension, and one value field:

readonly provider = new AgridProvider<Sale>({
  columns: [
    { field: 'region', header: 'Region' },
    { field: 'quarter', header: 'Quarter' },
    { field: 'revenue', header: 'Revenue', type: 'number' },
  ],
  datasource: new AgridDataSource(sales),
  pivotConfig: {
    rowField: 'region',
    columnField: 'quarter',
    valueField: 'revenue',
    aggregate: 'sum',
  },
});

Supported aggregates are sum (default), avg, min, max, count, and custom functions. Source updates regenerate the pivot. Filtering, sorting, selection, and pagination remain available; editing, row mutation, tree mode, server-side row models, and aggregate footers do not. Set showSidebar: true to expose a Pivot tab that changes dimensions, values, and built-in aggregates directly from the table. The tab also repeats the generated-column visibility selector so pivot configuration and display choices can be managed in one place.

Persist the complete JSON-safe state with the provider or component API:

const settings = provider.saveSettings(); // AgridSettings
await backend.save(settings);

provider.loadSettings(await backend.load());

The snapshot includes pivotConfig plus AgridControlState (visibility, widths, order, pinning, filters, sorting, pagination, and aggregates). Sidebar pivot and visibility changes also emit the full object through (settingsChange). Custom aggregate functions are intentionally rejected because functions cannot be serialized safely.

AgridPageSelectorComponent navigates a labeled list using previous/next buttons, a typed ID, or a dropdown. Every navigation path emits the complete selected item through (selectPage).

readonly pages: AgridPageItem<number>[] = Array.from({ length: 100 }, (_, index) => ({
  id: index + 1,
  label: `Page ${index + 1}`,
}));
readonly selectedPageId = signal(1);

selectPage(item: AgridPageItem<number>): void {
  this.selectedPageId.set(item.id);
}

<agrid-page-selector [items]="pages" [selectedId]="selectedPageId()"
  (selectPage)="selectPage($event)" />

IDs may be strings or numbers. Type an exact ID and press Enter to jump. The component uses the shared --agrid-color-* theme variables and accepts optional labels plus a disabled state.

Configure menuBarItems to render commands above the column headers. Main buttons and dropdown items share the single (menuBarAction) output. visible, active, and disabled accept either a boolean or a resolver receiving current rows, selected rows, selected cell, provider, and datasource.

readonly provider = new AgridProvider<Order>({
  columns,
  datasource,
  rowSelection: 'multi',
  menuBarItems: [
    { id: 'refresh', label: 'Refresh', icon: '↻' },
    {
      id: 'selection',
      label: 'Selection',
      disabled: ({ selectedRows }) => selectedRows.length === 0,
      active: ({ selectedRows }) => selectedRows.length > 0,
      items: [
        { id: 'approve', label: 'Approve', visible: ({ selectedRows }) => selectedRows.length > 0 },
        { id: 'archive', label: 'Archive', disabled: ({ selectedRows }) => selectedRows.some(({ row }) => row.locked) },
      ],
    },
  ],
});

onMenuBarAction(id: string): void {
  // refresh, selection, approve, archive, ...
}

<agrid [provider]="provider" (menuBarAction)="onMenuBarAction($event)" />

Three options are WritableSignal properties on the provider instance — update them at runtime without recreating the provider:

Example — toggle readonly in a host component:

readonly provider = new AgridProvider({ ..., readonly: true });
readonly isEditing = signal(false);

constructor() {
  effect(() => this.provider.control.setReadonly(!this.isEditing()));
}

Example — server-side loading state:

async loadPage(page: number) {
  this.provider.control.setLoading(true);
  this.ds.setData(await fetchPage(page));
  this.provider.control.setLoading(false);
}

Call these through viewChild(AgridComponent).

Export lives on the provider, so you can trigger it from anywhere that holds the provider — no viewChild(AgridComponent) required:

provider.exportCsv();                  // downloads "export.csv"
provider.exportCsv('employees.csv');

provider.exportXlsx();                 // downloads "export.xlsx"
provider.exportXlsx('employees.xlsx');

Both use display values (value-list labels, formatters) and respect column visibility; group-header rows are excluded. exportXlsx writes a real .xlsx workbook with zero third-party dependencies — numbers and dates are emitted as native, sortable/summable cells under a bold frozen header row. Both methods operate on the grid's current filtered, visible projection and are a no-op until an <agrid> bound to the provider has rendered.

ColDef describes one column.

Columns, providers, datasources, and row events accept a row type. Supplying it makes column fields and callback values type-safe:

interface PersonRow {
  id: number;
  name: string;
  active: boolean;
}

const columns: ColDef<PersonRow>[] = [
  { field: 'id', header: 'ID', formatter: value => value.toFixed(0) },
  { field: 'name', header: 'Name', formatter: value => value.toUpperCase() },
  {
    field: 'active',
    header: 'Active',
    values: [
      { value: true, label: 'Yes' },
      { value: false, label: 'No' },
    ],
  },
];

const datasource = new AgridDataSource<PersonRow>([]);
const provider = new AgridProvider<PersonRow>({ columns, datasource });

function onRecordEdit(event: RecordEditEvent<PersonRow>): void {
  console.log(event.data.name);
}

An invalid field such as { field: 'email' } is rejected by TypeScript. Generic parameters are optional, so existing untyped configurations remain compatible.

const columns: ColDef<PersonRow>[] = [
  { field: 'firstName', header: 'First name', group: 'employee' },
  { field: 'lastName', header: 'Last name', group: 'employee' },
  { field: 'email', header: 'Email' },
];

const provider = new AgridProvider({
  columns,
  headerGroups: [{ id: 'employee', label: 'Employee' }],
});

The extra header row appears when a visible column references a configured group. Only adjacent columns share one group header. Reordering, hiding, or pinning columns can split the same group ID into multiple rendered segments. Dragging a group header moves every column in that segment as one ordered block. A segment containing a locked column cannot be dragged. The group property is only for header presentation; groupable continues to control data-row grouping.

interface ColDef {
  field: string;
  header: string;
  group?: string;          // references AgridProvider.headerGroups
  headerMenuItems?: AgridColumnHeaderMenuItem[];
  width: number;           // use ColDefAutoSize (-1) to autosize on first render
  type?: 'text' | 'number' | 'date' | 'boolean';
  editable?: boolean;
  cellReadonly?: (params: { value: unknown; row: Record<string, unknown>; column: ColDef; originalIndex: number }) => boolean;
  textAlign?: 'left' | 'center' | 'right' | Signal<'left' | 'center' | 'right'>;
  cellFormat?: (params: { value: unknown; row: Record<string, unknown>; column: ColDef; originalIndex: number }) => CellFormat | null | undefined;
  colSpan?: number | ((params: { value: unknown; row: Record<string, unknown>; column: ColDef; originalIndex: number }) => number);
  locked?: boolean;
  values?: string[] | ValueOption[];
  formatter?: (value: unknown) => string;
  inputMask?: (params: { value: unknown; row: Record<string, unknown>; column: ColDef }) => RegExp | null;
  filterable?: boolean;
  groupable?: boolean;
  hidden?: boolean;
  pinned?: 'left' | 'right';
  aggregate?: 'sum' | 'avg' | 'min' | 'max' | 'count';
  cellRenderer?: (params: { value: unknown; row: Record<string, unknown> }) => string;
  cellClass?: (params: { value: unknown; row: Record<string, unknown> }) => string;
  infoIcon?: boolean | ((params: { value: unknown; row: Record<string, unknown> }) => boolean);
}

Use a host-owned writable signal when alignment must change at runtime. Pass that signal into the column definition and update the original signal from columnHeaderAction:

import { signal } from '@angular/core';
import { ColDef, ColumnHeaderActionEvent } from '@thkl/agrid';

type TextAlign = 'left' | 'center' | 'right';

readonly salaryAlignment = signal<TextAlign>('right');

readonly columns: ColDef<Employee>[] = [
  {
    field: 'salary',
    header: 'Salary',
    textAlign: this.salaryAlignment,
    headerMenuItems: [
      { key: 'align-left', label: 'Align left' },
      { key: 'align-center', label: 'Align center' },
      { key: 'align-right', label: 'Align right' },
    ],
  },
];

onColumnHeaderAction(event: ColumnHeaderActionEvent<Employee>): void {
  if (event.column.field !== 'salary') return;

  const alignment = event.key.replace('align-', '') as TextAlign;
  this.salaryAlignment.set(alignment);
}

<agrid [provider]="provider" (columnHeaderAction)="onColumnHeaderAction($event)" />

Do not assign a new string to event.column.textAlign for runtime changes. A column definition is configuration rather than reactive state, so mutating the object does not notify rendered cells. Also, event.column.textAlign is typed as a static value or a read-only Signal; retain the original writable signal when calling .set().

Use colSpan to merge adjacent cells horizontally for selected rows:

const columns: ColDef<OrderRow>[] = [
  {
    field: 'label',
    header: 'Label',
    textAlign: 'center',
    colSpan: ({ row }) => row.kind === 'summary' ? 3 : 1,
  },
  { field: 'quantity', header: 'Quantity' },
  { field: 'total', header: 'Total' },
];

The callback receives the typed row, value, column, and original datasource index. Values are rounded down and clamped to the columns remaining in the current pane. A span cannot cross from a left-pinned pane into the scrollable pane or from the scrollable pane into a right-pinned pane.

<agrid [provider]="provider" (cellInfo)="showCellInfo($event)" />

Return a mask per row when string values need a structured format:

{
  field: 'reference',
  header: 'Reference',
  inputMask: ({ row }) =>
    row.numeric
      ? /\d{0,3}(?:-\d{0,5}(?:-\d{0,5})?)?/
      : /[a-z0-9]{0,3}(?: [a-z0-9]{0,3}(?: [a-z0-9]{0,5})?)?/i,
}

The expression is matched against the entire proposed value, so explicit ^ and $ anchors are optional. It must accept partial input, including the empty string and any intermediate separators users need to type. Return null when a particular row should use an unrestricted text editor.

Import ColDefAutoSize and use it as the width value to fit the column to its content on first render:

import { ColDefAutoSize } from './agrid';

const columns: ColDef[] = [
  { field: 'name', header: 'Name', width: ColDefAutoSize },
  { field: 'email', header: 'Email', width: ColDefAutoSize },
];

The column sizes itself once on first render and then behaves like a normal resizable column.

Use value options when stored values differ from labels.

interface ValueOption {
  value: unknown;
  label: string;
}

Example:

{
  field: 'departmentId',
  header: 'Department',
  width: 140,
  values: [
    { value: 1, label: 'Engineering' },
    { value: 2, label: 'Sales' },
  ],
}

The grid displays labels, but committed edits store value.

The grid automatically detects and formats date values without any configuration. Both display and sorting use the native date value.

Auto-detected formats:

• Date objects
• ISO 8601 strings: "2024-01-15", "2024-01-15T10:30:00Z", "2024-01-15T10:30:00+02:00"

Display: Values are formatted using the browser's locale — e.g. Jan 15, 2024.

Sorting: Date columns sort chronologically by raw timestamp, not alphabetically by display string.

Priority: values list → formatter → date auto-format → raw string.

To force date formatting on a column regardless of value shape, set type: 'date'.

To use a custom date format, set formatter:

{ field: 'hiredAt', header: 'Hired', width: 120,
  formatter: v => new Date(v as string).toLocaleDateString('de-DE') }

Alternating row shading is opt-in via the provider:

readonly provider = new AgridProvider({ ..., zebraStripes: true });

Override the stripe color with a CSS custom property on the host:

agrid {
  --agrid-color-bg-stripe: #f0f4ff;
}

Hover and selection colors always override the stripe.

Set readonly: true in the provider to make the entire grid non-editable:

readonly provider = new AgridProvider({ ..., readonly: true });

To toggle readonly at runtime, update the control:

readonly isReadonly = signal(true);

constructor() {
  effect(() => this.provider.control.setReadonly(this.isReadonly()));
}

Individual ColDef.editable: false still works when readonly is false.

Pagination is controlled through AgridControl. When a page size is set the grid renders a page bar at the bottom showing « ‹ page / total › » and the total filtered row count.

readonly gridControl = new AgridControl({ pageSize: 25 });

Or change it at runtime:

this.gridControl.setPageSize(10);  // 0 = show all rows
this.gridControl.setPage(2);

Pagination applies to data rows after filtering and sorting, before grouping. Each page therefore always contains at most pageSize data rows.

Enable serverSideFiltering when the API should filter and sort the dataset:

readonly provider = new AgridProvider({
  columns: [
    { field: 'name', header: 'Name', filterable: true },
    { field: 'status', header: 'Status', filterable: true },
  ],
  datasource: this.ds,
  control: this.ctrl,
  serverSideFiltering: true,
  sortOption: 'single',
});

<agrid
  [provider]="provider"
  (serverQueryChange)="loadRows($event)"
/>

loadRows(query: AgridServerQuery): void {
  this.api.orders(query).subscribe(result => {
    this.ds.setData(result.rows);
    this.ctrl.setTotalRows(result.total);
  });
}

For signal-backed stores, subscribe to the provider instead of template outputs:

effect(() => {
  const query = this.provider.serverQuery();
  if (!query) return;
  this.store.load(query);
});

In server-side mode:

• Filter and sort state remains visible in the grid headers.
• The grid does not filter or sort loaded rows locally.
• The distinct-value checklist is hidden unless ColDef.values supplies the complete server-side value set.
• AgridServerQuery contains column filters, value selections, menu conditions, ordered sorts, quick-filter text, and page range.
• Clearing emits an empty filter value, selectedValues: null, or a null sort direction on the compatibility outputs.
• Multi-column sorting emits one event for each changed column.
• Text filter events are debounced by filterDebounceMs (300 ms by default).

Use sortOption: 'single' for backends that accept only one sort field. Selecting another column clears the previous sort first. Use 'none' to remove sorting controls completely; 'multi' preserves the default multi-column behavior.

The grid updates its visible filter state immediately, but only emits the final server text or condition value after the debounce delay. Set filterDebounceMs: 0 when immediate events are required. For server pagination, set a pageSize, call control.setTotalRows(total) after each response, and replace the datasource contents with the returned page.

Use AgridServerSideRowModel when rows should be loaded in blocks as the virtual viewport scrolls. Global row indices remain stable, unloaded rows render as placeholders, stale responses are ignored after query changes, and old blocks are evicted at the configured cache limit.

const rowModel = new AgridServerSideRowModel<Order>({
  blockSize: 100,
  maxBlocksInCache: 8,
  initialRowCount: 1_000_000, // optional; the server can return rowCount instead
  datasource: {
    async getRows(request) {
      const response = await api.searchOrders(request);
      return { rows: response.rows, rowCount: response.total };
    },
  },
});

const provider = new AgridProvider<Order>({
  columns,
  serverSideRowModel: rowModel,
  enableQuickFilter: true,
});

Requests contain the half-open startRow/endRow range, complete column filter state, ordered sort entries, and the quick-filter string. Returning rowCount sets the exact scrollbar extent. Without it, a short block marks the end and a full block extends the unknown extent by one block.

The initial row model is flat: client-side grouping, tree data, pinned rows, master/detail, pagination, and local aggregate footers are not applied. Editing updates the loaded cache; persist edits from grid events because an evicted block is fetched again.

Point ColDef.cellRendererComponent at any standalone Angular component to control the cell's display (read) state. The component injects AGRID_RENDERER_CONTEXT to read the value, row, and column as signals — with full Angular bindings, event handlers, and child components, and no manual HTML escaping or sanitization. This needs no third-party dependency.

import { AGRID_RENDERER_CONTEXT } from '@thkl/agrid';

@Component({
  selector: 'status-badge',
  template: `<span class="badge" [class]="'badge--' + value()">{{ value() }}</span>`,
})
export class StatusBadge {
  private readonly ctx = inject(AGRID_RENDERER_CONTEXT);
  readonly value = computed(() => String(this.ctx.value() ?? ''));
}

@Component({
  selector: 'score-bar',
  template: `<span class="track"><span class="fill" [style.width.%]="value()"></span></span>`,
})
export class ScoreBar {
  private readonly ctx = inject(AGRID_RENDERER_CONTEXT);
  readonly value = computed(() => Number(this.ctx.value() ?? 0));
}

const columns: ColDef[] = [
  { field: 'status', header: 'Status', editable: false, cellRendererComponent: StatusBadge },
  { field: 'score', header: 'Performance', editable: false, cellRendererComponent: ScoreBar },
];

A component renderer also works for boolean columns, replacing the default checkbox. See the Custom cells demo for badge and score-bar renderers.

Deprecated. Prefer cellRendererComponent. The string renderer remains supported for now but will be removed in a future release.

Return an HTML string from cellRenderer to render content in a cell. Angular's built-in sanitization runs automatically. Use CSS classes rather than inline styles, and escape dynamic text before interpolating it into HTML.

const columns: ColDef[] = [
  {
    field: 'status',
    header: 'Status',
    editable: false,
    cellRenderer: ({ value }) =>
      `<span class="status-badge status-badge--${value}">${value}</span>`,
  },
];

The row parameter gives you access to the full row object. When both are set, cellRendererComponent wins.

When the built-in text input, dropdown, or checkbox isn't enough, point ColDef.cellEditor at any standalone Angular component. The grid instantiates it while the cell is in edit mode and provides an AgridEditorContext through dependency injection. The editor is purely an input surface — the grid keeps ownership of validation (validate), undo/redo history, and the commit/cancel lifecycle, so Tab, Enter, and Escape keep working without any extra wiring (their key events bubble up to the grid). This needs no third-party dependency — just Angular.

Inject AGRID_EDITOR_CONTEXT to talk to the grid:

import { AGRID_EDITOR_CONTEXT } from '@thkl/agrid';

@Component({
  selector: 'star-rating-editor',
  template: `
    @for (n of [1, 2, 3, 4, 5]; track n) {
      <button type="button" (click)="pick(n)">{{ n <= value() ? '★' : '☆' }}</button>
    }`,
})
export class StarRatingEditor {
  private readonly ctx = inject(AGRID_EDITOR_CONTEXT);
  readonly value = signal(Number(this.ctx.value() ?? 0));

  pick(n: number): void {
    this.value.set(n);
    this.ctx.setDraft(n);   // stage the value the grid will commit
    this.ctx.commit();      // confirm immediately (optional — Tab/Enter also commit)
  }
}

const columns: ColDef[] = [
  {
    field: 'rating',
    header: 'Rating',
    type: 'number',
    cellEditor: StarRatingEditor,
    cellRenderer: ({ value }) => '★'.repeat(Number(value)), // how it looks when not editing
  },
];

Pair cellEditor with cellRenderer to control how the value looks when the cell isn't being edited. See the Custom editors demo for star-rating, colour-swatch, and slider editors.

AgridChartComponent renders zero-dependency SVG charts/graphs — column, bar, line, area, pie, and donut — configured exactly like the grid: build an AgridChartProvider and pass it in.

import { AgridChartComponent, AgridChartProvider } from '@thkl/agrid';

readonly chartProvider = new AgridChartProvider({
  type: 'column',
  data: {
    categories: ['Q1', 'Q2', 'Q3', 'Q4'],
    series: [
      { name: 'North', values: [120, 145, 138, 162] },
      { name: 'South', values: [98, 110, 134, 128] },
    ],
  },
  height: 300,
});

<agrid-chart [provider]="chartProvider" />

The chart sizes itself to its container width (observed) and the provider's height. Every option is a signal: type is writable, so chartProvider.type.set('pie') re-renders.

Pie and donut charts use the first series; its values become slices labelled by categories.

Pass a grid provider's visibleRows as the source and the chart follows the grid live — including its filters and sorting:

readonly chartProvider = new AgridChartProvider<RegionRow>({
  type: 'column',
  source: this.gridProvider.visibleRows,           // filtered + sorted rows
  transform: (rows, type) => ({
    categories: rows.map(r => r.region),
    series: [{ values: rows.map(r => r.total) }],
  }),
});

AgridProvider.visibleRows is a Signal<readonly T[]> of the grid's current rows. Important semantics:

• It reflects filtering and sorting — filter a row out of the grid and it leaves the chart too.
• It deliberately ignores grouping and pagination: a chart wants the whole filtered set, not a single page or grouped subtotals. (Use a transform to aggregate if you want grouped totals.)
• It is published by the rendered grid component. Before the grid mounts (or with no grid attached) it falls back to every datasource row.

With a source the dataset is a derived signal, so setData() is unavailable — update the source or the transform instead. Without a source, use chartProvider.setData(next) to replace static data.

See the Charts demo for a grid beside a chart with a type switcher. The main demo also has a Show Charts menu action that opens a graph panel linked to the grid's filtered rows. In both cases, filtering a row or editing a cell redraws the chart instantly.

Fit all visible columns to their content after loading data:

constructor() {
  afterNextRender(() => this._grid()?.autosizeAllColumns());
}

Or autosize a single column by double-clicking its resize handle, or through the column menu.

AgridDataSource<T> is a signal-based row container shared by the host and grid.

const ds = new AgridDataSource<Record<string, unknown>>([
  { id: 1, name: 'Alice' },
]);

Link a writable Angular signal directly when the application and grid should share ownership of the rows:

interface Row {
  id: number;
  name: string;
}

readonly rows = signal<Row[]>([
  { id: 1, name: 'Alice' },
]);
readonly ds = new AgridDataSource<Row>();
readonly provider = new AgridProvider({
  columns: [
    { field: 'id', header: 'ID', editable: false },
    { field: 'name', header: 'Name' },
  ],
  datasource: this.ds,
});

constructor() {
  this.ds.linkSignal(this.rows);
}

No synchronization effect() is needed. Updates work in both directions:

• Calling rows.set(...) or rows.update(...) refreshes the grid.
• Cell edits, paste, setData, updateRow, patchRow, addRow, removeRow, and moveRow update rows automatically.
• Undo and redo also update rows because they use datasource mutations.

The (cellEdit) output is not required to keep the writable signal synchronized. Use it only for side effects such as saving changes to an API:

<agrid [provider]="provider" (cellEdit)="saveEdit($event)" />

For one-way linking, pass a readonly signal:

readonly rows = signal<Row[]>([]);

constructor() {
  this.ds.linkSignal(this.rows.asReadonly());
}

In this mode, source updates refresh the grid, but grid mutations remain local to the datasource. In both modes, source updates are linked without copying the source array.

AgridControl stores optional grid UI state and behavior. Assign it to AgridProvider.control to enable persisted state, filters, sort, grouping, visibility, pinning, row reorder, pagination, and undo/redo.

const control = new AgridControl({
  allowRowReorder: true,
  hiddenColumns: ['salary'],
  pinnedColumns: ['id'],
  pageSize: 20,
});

interface AgridControlState {
  columnWidths: Record<string, number>;
  filters: Record<string, ColumnFilter>;
  allowRowReorder?: boolean;
  groupByField?: string | null;
  hiddenColumns?: string[];
  columnOrder?: string[];
  pinnedColumns?: string[];
  pageSize?: number;
  currentPage?: number;
}

The header arrow opens the complete column menu. The condition button beside an inline filter opens only condition operators and operands. Each trigger toggles its own menu mode.

interface ColumnFilter {
  text: string;
  selectedValues: string[] | null;
  sort: 'asc' | 'desc' | null;
}

text, selectedValues, and sort are combined when rows are displayed. selectedValues: null means all values are allowed.

firstDataRendered fires once per grid component, after the first completed render that contains real datasource rows. If the datasource starts empty, the event waits until rows are supplied. Server-side loading placeholders do not trigger it.

<agrid [provider]="provider" (firstDataRendered)="onGridReady($event)" />

interface FirstDataRenderedEvent<T> {
  rows: readonly T[];
  rowCount: number;
  provider: AgridProvider<T>;
  datasource: AgridDataSource<T>;
}

interface GridEditEvent {
  position: CellPosition;
  field: string;
  oldValue: unknown;
  newValue: unknown;
}

Emitted whenever a committed grid operation changes a cell.

interface FilterChangeEvent {
  field: string;
  value: string;
  selectedValues?: readonly string[] | null;
  operator?: FilterOperator | null;
  operand?: string | null;
  operand2?: string | null;
}

An empty value clears the server-side text filter. selectedValues: null clears a value-list filter. Condition filters include operator, operand, and operand2.

interface AgridServerQuery {
  filters: Readonly<Record<string, ColumnFilter>>;
  sort: readonly { field: string; direction: 'asc' | 'desc' }[];
  quickFilter: string;
  page: number;
  pageSize: number;
  startRow: number;
  endRow: number; // inclusive
}

Emitted by (serverQueryChange) and published as provider.serverQuery.

interface SortChangeEvent {
  field: string;
  direction: 'asc' | 'desc' | null;
}

A null direction clears the server-side sort for that field.

interface CellPosition {
  rowIndex: number;
  colIndex: number;
}

rowIndex is the original data-source row index. colIndex is the visible column index.

interface RowSelectEvent {
  rows: { row: Record<string, unknown>; originalIndex: number }[];
}

rowSelect emits null when selection is cleared.

interface CellSelectEvent<T> {
  position: CellPosition;
  row: T;
  originalIndex: number;
  field: keyof T;
  value: T[keyof T];
  column: ColDef<T>;
}

cellSelect emits null when selection is cleared. Use grid.getCurrentCell() to read the same shape on demand.

interface RowReorderEvent {
  row: Record<string, unknown>;
  oldIndex: number;
  newIndex: number;
}

The grid does not reorder rows itself on drop. Call dataSource.moveRow(event.oldIndex, event.newIndex) in the handler.

interface NewRecord {
  index: number;
  data: Record<string, unknown>;
  provider: AgridProvider;
  datasource: AgridDataSource;
}

For repeated grids, use the source carried by the event instead of looking the provider up by the row or loop index:

onPrepareAdd(event: NewRecord): void {
  const next = event.datasource.length;
  event.datasource.patchRow(event.index, { id: next, departmentId: 1 });
}

Emitted after the grid inserts a blank row. Patch defaults from the host if needed.

interface RowUpdateEvent<T extends object = Record<string, unknown>> {
  row: T;
  originalIndex: number;
}

rowChanged carries the latest complete datasource row and its current zero-based index. Inline edits are grouped until the active row is left. Sidebar-only editing emits the same event when the Save button is clicked.

interface GroupAction {
  label: string;
  action: (groupLabel: string) => void;
}

Actions appear in group header menus.

interface HistoryEntry {
  rowIndex: number;
  field: string;
  oldValue: unknown;
  newValue: unknown;
}

type HistoryItem = HistoryEntry | HistoryEntry[];

Paste and fill store multiple entries as one HistoryItem, so Ctrl/Cmd+Z reverses the whole operation.

Opening find clears the active cell so typing remains in the find input. Tree searches include collapsed descendants; navigating to one expands its ancestor path before scrolling to the match. | Click cell | Select cell. | | Shift+click cell | Extend range selection. | | Drag across cells | Select a rectangular range; dragging beyond the viewport auto-scrolls. | | Double-click cell | Start editing. | | Drag fill handle | Fill selected value/range down or right. | | Double-click resize handle | Autosize column. | | Drag resize handle | Resize column. | | Drag header | Reorder columns when control is provided. | | Right-click control cell | Open row context menu. |

• A filter row appears when at least one visible column has filterable: true.
• Text filter and value picker are combined.
• Sort is single-column. Setting sort on one field clears sort on other fields.
• Date columns sort chronologically by raw value, not alphabetically by display string.
• Grouping is enabled per column with groupable: true.
• Group state is controlled through AgridControl.setGroupBy(field | null).
• expandGroups() and collapseGroups() can be called on the component.

• Copy exports the active cell or selected rectangular range as TSV.
• With enableRowMarking, clicking a row header outside its nested controls or using its checkbox toggles the mark and emits rowMark.
• With showRowNumbers, the control column displays 1-based row numbers for the current filtered and sorted row order instead of the drag-handle glyph.
• Marked rows are appended to every copy using the copied columns.
• Copying without an active cell copies all visible columns from the marked rows.
• Context-menu Copy cell and Copy row also include marked rows without duplicates.

Selecting a numeric cell or rectangular range shows a status bar beneath the grid body with Count, Sum, Average, Minimum, and Maximum. It updates immediately when the range, projected rows, columns, or datasource values change and hides when the selection contains no numeric values.

Actual finite numbers are included in every column. Numeric strings are included only when their column declares type: 'number', preventing IDs and numeric-looking text from being aggregated by accident. Group headers, detail panels, loading rows, blanks, NaN, and infinite values are skipped.

The raw values are also available programmatically:

const summary = grid.selectionSummary();
// { count, sum, average, min, max } | null

The dedicated /selection-summary demo shows Shift+click and drag selection across comparable regional revenue columns and mirrors the raw signal above the grid.

• Row marking is independent from row selection.
• Marked rows remain part of copy output when filters hide them.
• Paste accepts TSV or CSV-like plain text and writes from the active cell.
• Pasted values use labels/raw values for values columns.
• Number columns coerce numeric pasted values to number.
• Paste skips read-only columns.
• Fill repeats the selected source block into the dragged target area.
• Paste and fill are each one undo history item.

Set masterDetail: true and provide a detailRenderer to make every data row expandable. A chevron appears in the control column; clicking it reveals a detail panel rendered beneath the row. The renderer returns an HTML string (sanitized automatically, like cellRenderer).

readonly provider = new AgridProvider<Order>({
  columns, datasource,
  masterDetail: true,
  detailRowHeight: 160, // fixed panel height in px (default 200)
  detailColumnField: 'notes',
  detailActions: [
    { id: 'follow-up', label: 'Follow-up', text: '\nFollow-up required.' },
    { id: 'customer', label: 'Customer', text: ({ row }) => `\nCustomer: ${row.customer}` },
  ],
  detailRenderer: ({ row }) => `<div class="order-detail">${row.notes}</div>`,
});

detailColumnField is optional. When set, the panel shows that column's formatted value below the custom renderer. If the linked cell is editable, click or Enter opens a multiline textarea. Blur or Ctrl/Cmd+Enter commits through normal validation, undo history, cellEdit, and recordEdit flows; Escape cancels. detailActions can add text-template buttons above the textarea; buttons insert at the current selection, or append when the editor is opened by the button. editable: false, cellReadonly, and grid read-only mode are respected.

Detail panels are sized by a built-in variable-height virtual-scroll strategy, so large lists stay performant whether or not panels are open. In tree mode, only leaf rows expose detail panels; parent rows continue to control tree expansion. Master/detail remains disabled while grouping. Toggle a panel imperatively with the public toggleDetail(originalIndex) / isDetailExpanded(originalIndex) methods on the component.

pinRow designates rows to keep fixed at the top or bottom of the body during vertical scroll — ideal for header or total/summary rows. Pinned rows are pulled out of grouping and pagination but keep their real data-source index, so editing, selection, and cell rendering work on them unchanged.

readonly provider = new AgridProvider<Order>({
  columns, datasource, // datasource includes a summary row
  pinRow: row => (row.isSummary ? 'bottom' : undefined),
});

Interactive pinning. Right-click any row (its cell context menu, or the control-cell row menu) to Pin row to top / bottom or Unpin row. A runtime override always wins over the pinRow predicate, so a user can unpin a declaratively-pinned row. Drive it programmatically with the public component methods pinRowTo(originalIndex, 'top' | 'bottom' | null) and rowPinState(originalIndex).

Pinned rows are designated over existing data-source rows (not a separate detached array). Keyboard arrow-navigation and range-selection do not currently cross the body↔pinned boundary.

getRowClass returns class names for a whole data row, complementing the per-cell ColDef.cellClass:

getRowClass: ({ row }) => (row.status === 'overdue' ? 'row-danger' : '')

Pinned columns are rendered in a fixed left pane. The unpinned columns render in a separate horizontally scrollable pane. Vertical scrolling is synchronized between the panes.

Pin columns initially with:

{ field: 'id', header: 'ID', width: 70, pinned: 'left' }

Or at runtime:

control.setPinned('id', true);

const saved = localStorage.getItem('agrid-state');
const control = AgridControl.fromJSON(saved ? JSON.parse(saved) : {});

localStorage.setItem('agrid-state', JSON.stringify(control.toJSON()));

Persisted state includes widths, filters, sort, grouping, hidden columns, column order, pinned columns, row reorder setting, page size, and current page.

The grid host is a flex column. Give it a defined height by participating in the parent's flex layout:

/* Angular Material card example */
mat-card {
  height: 600px;
  display: flex;
  flex-direction: column;
}

mat-card-content {
  flex: 1;
  min-height: 0;
  display: flex;
  flex-direction: column;
  padding: 0;
}

agrid {
  flex: 1;
  min-height: 0;
}

Override these on the agrid host element to theme the grid.

pnpm install
pnpm start
pnpm build          # publishable package
pnpm build:demo
pnpm copy:local     # uncompiled runtime sources in localdist/agrid
pnpm test
pnpm test:e2e
pnpm test:performance

The TypeScript compile check:

./node_modules/.bin/tsc --noEmit -p tsconfig.app.json

The Playwright suite starts the Angular demo server automatically and runs the grid interaction tests in Chromium. Install its browser once when setting up a new environment:

pnpm exec playwright install chromium

pnpm test:performance runs the isolated large-dataset suite serially against 10k, 50k, 100k, and 250k rows. It reports initial render, filtering, sorting, grouping, aggregation, row updates, and virtual-scroll timings without enforcing machine-dependent thresholds. The same operations can be run manually at /performance.

pnpm build:lib increments the package patch version and creates the publishable Angular package in dist/agrid-package. Inspect the package contents with:

cd dist/agrid-package
npm pack --dry-run

pnpm copy:local recreates localdist/agrid with only the library's runtime .ts, .html, and .css files. Tests, documentation, licenses, package metadata, and build configuration are excluded, making the directory suitable for source-level debugging in another Angular workspace.