Angular directives
The same primitives and hooks for Angular, from @fragiola/data-grid-angular, and how each React prop maps onto directives, templates and injection functions.
@fragiola/data-grid-angular has every primitive of the React package, as an Angular 22
attribute directive on your own element, and every hook as an injection function, over the same
core (re-exported whole). The behaviour, the data-* attributes, the ARIA and the structural
style of every element are the same: the other pages of these docs describe each part, and this
page says how its React API is written in Angular.
import {
DATA_GRID,
createDataGridRef,
injectDataGrid,
injectRowWindow,
templateContent,
type Column,
type DataGridNode,
} from "@fragiola/data-grid-angular";The directives are standalone: import DATA_GRID (every directive) in a component. They are
zoneless and OnPush-safe: the grid's view is a signal fed by the engine, and scrolling within
the rendered window changes no signal at all.
Your elements, your templates
A React part renders an element, render swaps it. In Angular the element is always yours: the
directive goes on it (a div, a tr, a td, a component's host), and the recursion is your
templates: <ng-template dataGridRows let-row> repeats its content for each rendered row, as
React's children function does. There is no default content: write the rows and cells out.
import { ChangeDetectionStrategy, Component, input } from "@angular/core";
import { type Column, DATA_GRID, type DataGridNode } from "@fragiola/data-grid-angular";
interface Person {
id: number;
name: string;
}
@Component({
selector: "app-people-grid",
imports: [DATA_GRID],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<div dataGridRoot [columns]="columns" [rows]="people()" [rowKey]="rowKey" style="height: 400px">
<div dataGridGrid aria-label="People">
<div *dataGridHeader class="bg-white">
<div dataGridHeaderRow>
<ng-template [dataGridHeaderCells]="columns" let-cell>
<div [dataGridHeaderCell]="cell"><ng-container *dataGridCellContent /></div>
</ng-template>
</div>
</div>
<div dataGridBody>
<ng-template [dataGridRows]="columns" let-row>
<div [dataGridRow]="row" class="border-b">
<ng-template [dataGridCells]="columns" let-cell>
<div [dataGridCell]="cell" class="px-3 data-active:outline-2">
<ng-container *dataGridCellContent />
</div>
</ng-template>
</div>
</ng-template>
</div>
</div>
</div>
`,
})
export class PeopleGrid {
readonly people = input.required<Person[]>();
readonly columns: Column<Person, DataGridNode>[] = [{ key: "name", name: "Name", width: 180 }];
readonly rowKey = (row: Person) => row.id;
}A part that renders only sometimes is a structural directive on its element:
*dataGridHeader (none without a header row), *dataGridEmpty (only while there are no rows),
*dataGridRowDetail (from /row-expansion, only while its row is expanded),
*dataGridSummary="'top'" (from /summary-rows, only while there are summary rows there), and
the elements of yours React gives through a hook: *dataGridGroupToggle (from /row-grouping),
*dataGridColumnResizer (from /column-resize), *dataGridFillHandle (from /fill),
*dataGridCellEdit (from /editing).
Typing by your row
The root infers your row type from its columns and rows. A template's context is typed by
what you give its directive: the columns ([dataGridRows]="columns") or the root
(#grid="dataGridRoot", then [dataGridRows]="grid"); without either, the row is unknown.
Columns are the core's Column<TRow, DataGridNode>.
Column renderers
A column's renderers (renderCell, renderHeaderCell, renderGroupCell, renderSummaryCell,
renderEditCell) return a DataGridNode: text (a string or a number), nothing, or a template with
its context, templateContent(template, context). *dataGridCellContent renders the default
content of the cell it is in, the renderer's template included. [dataGridTemplate] types the
template's variables by its context.
@Component({
imports: [DATA_GRID],
template: `
<ng-template #nameCell [dataGridTemplate]="nameContext" let-row="row">
<b>{{ row.name }}</b>
</ng-template>
<!-- the grid, its cells rendering <ng-container *dataGridCellContent /> -->
`,
})
export class PeopleGrid {
readonly nameContext = contextOf<CellTemplateProps<Person>>();
@ViewChild("nameCell", { static: true })
private readonly nameCell!: TemplateRef<TemplateContext<CellTemplateProps<Person>>>;
readonly columns: Column<Person, DataGridNode>[] = [
{ key: "name", name: "Name", width: 180, renderCell: (props) => templateContent(this.nameCell, props) },
];
}A renderer runs for every cell it renders, so read its template through a static query
(@ViewChild(…, { static: true }), resolved once when the component is created): a signal query
(viewChild()) is marked dirty by every view the grid creates and collected again on the next
read, which makes a grid of many templated cells slow to render.
The template renders with the props the renderer was given, as its $implicit too
(let-props); a new context for the same template updates its view in place.
How React's props map
| React | Angular |
|---|---|
<DataGrid.X> | the directive [dataGridX] on your element (DataGridX): DataGrid.Root is dataGridRoot, DataGrid.Cell is [dataGridCell]="cell" |
render={<table />}, render={(props, state) => …} | your own element: <table dataGridGrid>, <td [dataGridCell]="cell"> |
children functions (Rows, Cells, HeaderRows, HeaderCells, SummaryRows, SummaryCells) | a template: <ng-template dataGridRows let-row>, <ng-template dataGridCells let-cell> |
| a part's default children (a cell's renderer or value) | <ng-container *dataGridCellContent /> inside the part |
className, style | your element's class and style, under the structural style (structural keys win; the layers and the pinned cells drop the keys the engine writes from your static style; never bind those keys yourself) |
className={(state) => …} | a data-* selector (data-active:outline-2), or the part's state: #cell="dataGridCell", then [class.active]="cell.state()?.active" |
onKeyDown, onClick, onPointerDown, onCopy, onPaste, … | your listeners ((keydown), (click), …): yours first, then the grid's keys, clicks, presses and clipboard on the root, so preventDefault in yours cancels the grid's |
features={features} | the input [features]="features" on the root, fixed when the grid is created |
a feature's props (sortColumns, activePosition, selectedRowKeys, selectedRange, onRangePaste, onFill, …) | its own directive's inputs and outputs, on the root's element (the table below): dataGridSorting with [(sortColumns)], dataGridNavigation with [(activePosition)], … |
Root's onXChange and the other callbacks | outputs without on: (rowWindowChange), (rowsEndReached), (expandedRowKeysChange) (on dataGridRowExpansion), …; [(expandedRowKeys)] binds both ways |
editingCell, onEditingCellChange, onCellEdit | dataGridEditing's [(editingCell)], [defaultEditingCell] and (cellEdit) ([dataGridEditing]="columns" types its row); from /editing |
onRowMove (given, rows move) | dataGridRowReorder on the root turns it on ([dataGridRowReorder]="false" off); its output (rowMove) tells |
onFill (given, cells fill) | dataGridFill on the root ([dataGridFill]="false" off), its output (fill); from /fill |
onBeforeRangePaste, onRangePaste | dataGridClipboard's input [beforeRangePaste] (a function: false refuses) and output (rangePaste); from /clipboard |
ref | your element's own template reference; a handle on the grid is a gridRef (createDataGridRef()) |
useX(…) hooks | injectX(…) injection functions (below) |
<DataGrid.Rows<Person>> and the other type arguments | [dataGridRows]="columns" (or the root) |
useColumnResizer, useRowDragHandle, useGroupToggle, useGroupLabel, useFillHandle, useCellEdit on your element | the directives *dataGridColumnResizer="cell", [dataGridRowDragHandle]="row" (/row-reorder), *dataGridGroupToggle="row" (/row-grouping), [dataGridGroupLabel]="cell", *dataGridFillHandle="cell", *dataGridCellEdit="let edit" |
A part's state() is undefined on the first pass of a binding on its own element (Angular
evaluates class bindings before the element's inputs), so read it with ?..
Directives
| directive | inputs | template context |
|---|---|---|
[dataGridRoot] | the core's root props (GridRootProps: columns, rows or rowCount + getRow, rowKey, the sizes, every piece of the core's state controlled or not, the engine's options), gridRef, features; the callbacks are outputs | |
[dataGridRoot][dataGridSorting] | sortColumns ([(sortColumns)] with the output sortColumnsChange), defaultSortColumns; from @fragiola/data-grid-angular/sorting, with sorting() in the root's features | |
[dataGridRoot][dataGridNavigation] | activePosition ([(activePosition)], the output activePositionChange), defaultActivePosition; from /navigation, with navigation() | |
[dataGridRoot][dataGridRowSelection] | rowSelection, isRowSelectable, selectedRowKeys ([(selectedRowKeys)]), defaultSelectedRowKeys; from /row-selection, with rowSelection() | |
[dataGridRoot][dataGridCellRange] | cellSelection, selectedRange ([(selectedRange)]), defaultSelectedRange; from /range, with cellRange() | |
[dataGridRoot][dataGridClipboard] | beforeRangePaste; the output rangePaste; from /clipboard, with clipboard() | |
[dataGridRoot][dataGridFill] | dataGridFill (on by presence, false off); the output fill; from /fill, with fillHandle() | |
[dataGridRoot][dataGridEditing] | what types cellEdit's row (optional), editingCell ([(editingCell)]), defaultEditingCell; the output cellEdit; from /editing, with editing() | |
[dataGridRoot][dataGridColumnResize] | columnWidths ([(columnWidths)], the output columnWidthsChange), defaultColumnWidths; from /column-resize, with columnResize() | |
[dataGridRoot][dataGridColumnReorder] | columnOrder ([(columnOrder)], the output columnOrderChange), defaultColumnOrder; from /column-reorder, with columnReorder() | |
[dataGridRoot][dataGridColumnGroupCollapse] | collapsedGroupKeys ([(collapsedGroupKeys)], the output collapsedGroupKeysChange), defaultCollapsedGroupKeys; from /column-group-collapse, with columnGroupCollapse() (columnPinning(), from /column-pinning, has no input) | |
[dataGridRoot][dataGridRowExpansion] | expandedRowKeys ([(expandedRowKeys)], the output expandedRowKeysChange), defaultExpandedRowKeys, detailHeight, estimatedDetailHeight; from /row-expansion, with rowExpansion() | |
[dataGridRoot][dataGridRowGrouping] | expandedGroupKeys ([(expandedGroupKeys)], the output expandedGroupKeysChange), defaultExpandedGroupKeys; from /row-grouping, with rowGrouping() | |
[dataGridRoot][dataGridRowReorder] | the rows move while it is present ([dataGridRowReorder]="false" stops them), the output rowMove; from /row-reorder, with rowReorder() | |
[dataGridRoot][dataGridFiltering] | columnFilters ([(columnFilters)], the output columnFiltersChange), defaultColumnFilters; from /filtering, with filtering() | |
[dataGridRoot][dataGridSearch] | searchText ([(searchText)], the output searchTextChange), defaultSearchText; from /search, with search() | |
[dataGridRoot][dataGridPagination] | pageIndex and pageSize ([(pageIndex)], [(pageSize)], the outputs pageIndexChange, pageSizeChange), defaultPageIndex, defaultPageSize, totalRowCount; from /pagination, with pagination() | |
[dataGridRoot][dataGridSummaryRows] | summaryRows, summaryRowHeight (DataGridSummaryRowsRoot); from /summary-rows, with summaryRows() (cellSpans(), from /spans, has no input) | |
[dataGridGrid] | none | |
*dataGridHeader | none | |
ng-template[dataGridHeaderRows] | what types it (optional) | { $implicit: row, row } |
[dataGridHeaderRow] | its header row (optional: the columns' row) | |
ng-template[dataGridHeaderCells] | what types it (optional) | { $implicit: cell, cell } |
[dataGridHeaderCell] | its cell | |
[dataGridBody] | none | |
ng-template[dataGridRows] | what types it (optional) | { $implicit: row, row } |
[dataGridRow] | its row | |
ng-template[dataGridCells] | what types it (optional) | { $implicit: cell, cell } |
[dataGridCell] | its cell | |
*dataGridCellContent | none: the cell it is in | |
*dataGridRowDetail (/row-expansion) | none: the row it is in | { $implicit: state, state } |
*dataGridEmpty | none | |
*dataGridSummary (/summary-rows, as the four below: SUMMARY_ROWS) | its position | { $implicit: state, state } |
ng-template[dataGridSummaryRows] | its position (optional: the summary's) | { $implicit: row, row } |
[dataGridSummaryRow] | its row | |
ng-template[dataGridSummaryCells] | what types it (optional) | { $implicit: cell, cell } |
[dataGridSummaryCell] | its cell | |
*dataGridColumnResizer (/column-resize), *dataGridGroupToggle (/row-grouping), *dataGridFillHandle (/fill) | a header cell, a row (or cell), a cell | { $implicit: state, state } |
[dataGridRowDragHandle] (/row-reorder), [dataGridGroupLabel] | a row (or cell), a group's header cell | |
*dataGridCellEdit | its cell (optional: the cell it is in) | { $implicit: edit, edit } |
[dataGridTemplate] | a context type (contextOf<…>()) | that context |
[dataGridBind] | an injection function's props() |
Each attribute directive is exported as its name (#row="dataGridRow") and has a state()
signal. Scrolling renders nothing until the rendered window changes: the engine writes the
layers' offsets itself, and Angular never writes them.
Injection functions
The hooks of the React package, as injection functions: call them in an injection context (a
constructor or a field). A part's takes its row or cell (a value, a signal or a getter) and
returns { state, props } as signals (PartInjectResult); put props() on your element with
[dataGridBind].
| function | returns |
|---|---|
injectDataGrid() | { model, engine } of the root around (read them once its inputs are set: in a listener, an effect, ngOnInit); with a gridRef, a signal of them, null until a root holds it. injectDataGrid<Person, typeof features>() types the features' keys |
createDataGridRef() | a handle on a grid for <div dataGridRoot [gridRef]="gridRef"> (React's useDataGridRef and createDataGridRef); createDataGridRef<Person, typeof features>() types the features' keys |
injectRowWindow(gridRef?), injectColumnWindow(gridRef?) | the rows or the columns in view and rendered (AxisWindow), as a signal |
injectGridView() | the grid's view, as a signal |
injectRows(), injectCells(row) | the rendered rows, a row's rendered cells |
injectHeaderRows(), injectHeaderCells(row?) | the header rows, a header row's cells |
/summary-rows's injectSummaryRows(position?), injectSummaryCells(row?) | the summary rows, a summary row's cells |
injectRow(row), injectCell(cell), injectHeaderCell(cell); /summary-rows's injectSummaryRow(row), injectSummaryCell(cell); /row-expansion's injectRowDetail(row) | a part's { state, props } |
/row-reorder's injectRowDragHandle(row), /row-grouping's injectGroupToggle(row), injectGroupLabel(cell), /column-resize's injectColumnResizer(cell), /fill's injectFillHandle(cell) | the { state, props } of an element of yours (the directives above are the shorter form; a measured row and a group label need theirs: the engine reads their element) |
/editing's injectCellEdit(cell) | the editor props of the cell being edited (EditCellRenderProps), null otherwise |
The opt-in entry points:
| entry | exports |
|---|---|
@fragiola/data-grid-angular/local | injectLocalRows(rows, columns, options?): rows in memory, sorted, filtered, searched, grouped and paged by the features in options.features (the root's list: sorting(), filtering(), search(), pagination(), each one's stage; one not installed is skipped), each field a getter; [dataGridLocalRows]="local" on the root gives it their props (React's {...local.props}): the rows and those features' state |
@fragiola/data-grid-angular/sorting | sorting(), the sorting feature; DataGridSorting, the directive holding the sort's inputs on the root; sortColumnsOf(view), headerCellSort, SortColumn (the core's, re-exported) |
@fragiola/data-grid-angular/navigation | navigation(), the keys and the active cell; DataGridNavigation; samePosition |
@fragiola/data-grid-angular/row-selection | rowSelection(), the row selection; DataGridRowSelection; its helpers (selectionStatus, withRowKeys, …); injectSelectAll(rowKeys, gridRef?): a "select all" control's state and its toggle, each field a getter |
@fragiola/data-grid-angular/range | cellRange(), ranges of cells (with navigation()); DataGridCellRange; keptRange, sameCellRange |
@fragiola/data-grid-angular/clipboard | clipboard() (with cellRange()); DataGridClipboard; parseTsv, toTsv, pastedRange, rangeText |
@fragiola/data-grid-angular/fill | fillHandle(), the fill handle (with cellRange()); DataGridFill; *dataGridFillHandle (DataGridFillHandle, FillHandleContext), injectFillHandle(cell); repeatedFill |
@fragiola/data-grid-angular/row-expansion | rowExpansion(), rows that expand; DataGridRowExpansion; *dataGridRowDetail (DataGridRowDetail, RowDetailContext), injectRowDetail(row) |
@fragiola/data-grid-angular/row-grouping | rowGrouping(), row groups and trees that expand; DataGridRowGrouping; *dataGridGroupToggle (DataGridGroupToggle, GroupToggleContext), injectGroupToggle(row) |
@fragiola/data-grid-angular/row-reorder | rowReorder(), rows moved; DataGridRowReorder; [dataGridRowDragHandle] (DataGridRowDragHandle), injectRowDragHandle(row) |
@fragiola/data-grid-angular/spans | cellSpans(), a column's colSpan in the body |
@fragiola/data-grid-angular/filtering | filtering(), the column filters as the model's state; DataGridFiltering (dataGridFiltering: [(columnFilters)], [defaultColumnFilters]); data-filtered on a filtered column's header cell |
@fragiola/data-grid-angular/search | search(), the search text as the model's state; DataGridSearch (dataGridSearch: [(searchText)], [defaultSearchText]) |
@fragiola/data-grid-angular/pagination | pagination(), the page and its size as the model's state, pageCount; DataGridPagination (dataGridPagination: [(pageIndex)], [(pageSize)], their defaults, [totalRowCount]) |
@fragiola/data-grid-angular/summary-rows | summaryRows(), the summary rows; DataGridSummaryRowsRoot (dataGridSummaryRows); the summary's directives (SUMMARY_ROWS: *dataGridSummary, [dataGridSummaryRows], [dataGridSummaryRow], [dataGridSummaryCells], [dataGridSummaryCell]) and inject functions; SummaryRowInfo, SummaryCellInfo, SummaryRowsFeatureProps |
@fragiola/data-grid-angular/editing | editing(), cells edited in place (with navigation()); DataGridEditing; *dataGridCellEdit (DataGridCellEdit, CellEditContext), injectCellEdit(cell); CellEditEvent, editActions, editCellPropsOf, EDITOR_ATTRIBUTE |
Features
A grid installs its features through the root's [features] input.
A feature's inputs are a directive of its own on the root's element, from the feature's entry:
sorting's is DataGridSorting. Without it imported, [sortColumns] is not a known input (strict
templates). A feature with no input to give (navigation() left uncontrolled) needs only
[features].
import { DATA_GRID } from "@fragiola/data-grid-angular";
import { navigation } from "@fragiola/data-grid-angular/navigation";
import { DataGridSorting, type SortColumn, sorting } from "@fragiola/data-grid-angular/sorting";
@Component({
selector: "app-people-grid",
imports: [DATA_GRID, DataGridSorting],
template: `
<div dataGridRoot [features]="features" dataGridSorting [(sortColumns)]="sortColumns" [columns]="columns" [rows]="people()">
<!-- … -->
</div>
`,
})
export class PeopleGrid {
readonly features = [navigation(), sorting()];
readonly sortColumns = signal<readonly SortColumn[]>([]);
// …
}With rows in memory, [dataGridLocalRows] gives the root the sort: leave dataGridSorting out,
and keep [features].
A directive of your own gives the root props the same way: inject DataGridRoot and call
root.addPropsSource(() => props), which returns the function that removes it (call it on
destroy). A source's props win over the root's inputs; with { inputs: true } they rank as the
root's own inputs instead, so another source ([dataGridLocalRows]) wins over them, as every
feature's directive does.
Types
| type | description |
|---|---|
DataGridNode | what a column's renderers return: text, nothing, or a TemplateContent |
TemplateContent<C>, TemplateContext<C> | a template with its context; the context a template renders with (C and its $implicit) |
ContextOf<C> | a context type for [dataGridTemplate] (contextOf<C>()) |
CellTemplateProps<TRow> | a body cell's render props (renderCell's) |
RowsContext, CellsContext, HeaderRowsContext, HeaderCellsContext; /summary-rows's SummaryRowsContext, SummaryCellsContext | the collection templates' contexts |
RowDetailContext (/row-expansion's), SummaryTemplateContext (/summary-rows's), ColumnResizerContext, GroupToggleContext (/row-grouping's), FillHandleContext (/fill's), CellEditContext (/editing's) | the structural parts' contexts |
RowInfo, CellInfo, HeaderRowInfo, HeaderCellInfo; /summary-rows's SummaryRowInfo, SummaryCellInfo | what the templates hand you, as in React |
DataGridContextValue, DataGridRef | the model and the engine; the handle on a grid |
PartInjectResult<State>, ValueOrSignal<T> | what a part's injection function returns; what it takes |
RootPropsSource<TRow, TFeatures>, RootPropsSourceOptions | what addPropsSource takes: the props a directive gives the root, and how they rank (inputs) |
React's <Part>Props, DivPrimitiveProps, PrimitiveProps, RenderedProps and RenderProp
have no Angular counterpart: a directive's inputs and your own element replace them.
Server rendering
Not supported yet in Angular: the Angular package renders in the browser. The React package's server rendering has no Angular counterpart today.