Mat-Datatable

July 19, 2026 · View on GitHub

Mat-Datatable

A simple data table with virtual scrolling using Angular Material.

Table of Contents

About The Project
Getting Started
Used Assets
Mat-Datatable Demo
API Reference
API Testing Harnesses
- Classes
- Interfaces
Roadmap
Hints On Possible Extensions
Contributing
- Changelog
License
Hints

About The Project

This project extends 'angular material table' so that it can be used as a replacement for ngx-datatable in one of my projects. Unluckily ngx-datatable seems to be dead as it is still on angular v12 and an update to a more recent angular version is not in sight.

Mat-Datatable implements a table with virtual scrolling, sorting and filtering. Only a minimal set of the functionality of ngx-datatable is implemented.

Screenshot

Try out the live demo.

(back to top)

Getting Started

To use this package in your project just follow these simple steps.

Prerequisites

The package can be used in Angular apps with Angular Material installed.

Installation

Install the package from npmjs:

npm install mat-datatable

Embed Mat-Datatable In Your Project

Use the component as a standalone Angular component. Some properties of mat-datatable must be configured in the component class (for example in app.component.ts):

import { Component } from '@angular/core';
import { MatDatatableComponent, MatColumnDefinition } from 'mat-datatable';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MatDatatableComponent],
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  protected dataStore = new MyTableDataStore<MyTableItem>();

  protected columnDefinitions: MatColumnDefinition<MyTableItem>[] = [
    {
      columnId: 'id',
      header: 'ID',
      cell: (row) => ({ type: 'string', text: row.id.toString() })
    },
    {
      columnId: 'name',
      sortable: true,
      resizable: true,
      header: 'Name',
      cell: (row) => ({ type: 'string', text: row.name })
    }
  ];

  protected displayedColumns: string[] = ['id', 'name'];
}

The cell callback returns a typed content descriptor, so you can render plain strings, mailto links or images without changing the table API:

cell: (row) => ({ type: 'mailtoLink', text: row.email, url: `mailto:${row.email}` });

Add Mat-Datatable to your HTML file (for example app.component.html):

<div class="content-table">
  <mat-datatable
    [columnDefinitions]="columnDefinitions"
    [displayedColumns]="displayedColumns"
    [dataStoreProvider]="dataStore"
    [trackBy]="trackBy"
    [withFooter]="true"
  >
    Loading...
  </mat-datatable>
</div>

The height of the element containing the mat-datatable must be set explicitly (for example app.component.scss):

.content-table {
  height: 400px;
  margin: 0 1em;
  overflow: auto;
}

The cell callback returns a typed content descriptor, so you can render plain strings, mailto links or images without changing the table API:

cell: (row) => ({ type: 'mailtoLink', text: row.email, url: `mailto:${row.email}` });

(back to top)

Used Assets

The component is based on Angular Material and uses Google Fonts and the Google Material Icons font. Both fonts are part of the project and not fetched via https.

(back to top)

Mat-Datatable Demo

Demo project to show all features of Mat-Datatable.

git clone git@github.com:BePo65/mat-datatable.git
cd mat-datatable
npm start

Navigate to http://localhost:4200

(back to top)

API Reference

import {
  MatDatatableComponent,
  MatColumnDefinition,
  CellValueString,
  CellValueImage,
  CellValueMailTo,
  MatSortDefinition,
  DataStoreProvider,
  FieldFilterDefinition,
  RowSelectionType
} from 'mat-datatable';

Classes

MatDatatableComponent

Standalone Angular component for rendering a virtualized Material table. The component is generic so the row type can be provided with the template parameter.

Inputs

Name	Description
`columnDefinitions: MatColumnDefinition<T>[]`	Column definitions for the table. The order of the definitions does not need to match the visible column order.
`displayedColumns: string[]`	List of visible column IDs in the order they should be rendered.
`rowSelectionMode: RowSelectionType`	Controls row selection behaviour. Supported values are `none`, `single` and `multi`.
`dataStoreProvider: DataStoreProvider<T>`	Data source implementation for the table.
`trackBy: TrackByFunction<T>`	Optional row identity function.
`withFooter: boolean`	Enables the footer row.

Outputs

Name	Description
`rowClick: EventEmitter<T>`	Emitted when a row is clicked.
`rowSelectionChange: EventEmitter<T[]>`	Emitted when the current selection changes.
`sortChange: EventEmitter<MatSortDefinition[]>`	Emitted when the active sort definition changes.

Name	Description
`activatedRow: T \| undefined`	Marks a row as active.
`selectedRows: T[]`	Contains the current selection.
`sortDefinitions: MatSortDefinition[]`	Gets or sets the current sort definition.
`filterDefinitions: FieldFilterDefinition<T>[]`	Gets or sets the active filter definition.
`firstVisibleIndexChanged: Observable<number>`	Emits the index of the first visible row.
`totalRowsChanged: Observable<number>`	Emits the total number of rows in the datastore.
`filteredRowsChanged: Observable<number>`	Emits the number of rows after filtering.

Name	Description
`scrollToRow(row: T)`	Scrolls the viewport so the given row becomes visible.
`reloadTable()`	Reloads the table from its datastore.

Parameters
rowsRange: RequestRowsRange	The range of rows to fetch.
sorts: FieldSortDefinition[]	The sort definitions to use.
filters: FieldFilterDefinition[]	The filter definitions to use.

Name	Description
`columnId: string`	The unique ID of the column.
`sortable?: boolean`	Enables sorting for the column.
`resizable?: boolean`	Enables resizing of the column.
`header: string`	The text shown in the header row.
`headerAlignment?: ColumnAlignmentType`	Header alignment.
`cell: (element: TRowData) => CellContentValue`	Returns the rendered cell content for the current row.
`cellAlignment?: ColumnAlignmentType`	Alignment of the cell content.
`width?: string`	Optional column width, for example `8em`.
`tooltip?: (element: TRowData) => string`	Optional tooltip callback.
`showAsSingleLine?: boolean`	Truncates the content to a single line.
`footer?: string`	Optional footer text.
`footerAlignment?: ColumnAlignmentType`	Footer alignment.
`footerColumnSpan?: number`	Optional number of columns the footer should span.

Name	Description
`columnId: string`	The `columnId` of the column to sort.
`direction: SortDirection`	The sort direction.

Name	Description
`startRowIndex: number`	The index of the first row to return.
`numberOfRows: number`	The number of rows to return.

Name	Description
`content: T[]`	The array of requested rows.
`startRowIndex: number`	The index of the first row returned.
`returnedElements: number`	The number of rows in `content`.
`totalElements: number`	The number of rows in the unfiltered datastore.
`totalFilteredElements: number`	The number of rows after filtering.

Name	Description
`type: 'string'`	Indicates that the cell content is plain text.
`text: string`	The text displayed in the cell.

Name	Description
`type: 'mailtoLink'`	Indicates that the cell content is rendered as a link.
`url: string`	The mail address or URL used for the link target.
`text: string`	The visible text shown for the link.

Name	Description
`type: 'image'`	Indicates that the cell content is rendered as an image.
`url: string`	The URL of the image to display.
`altText: string`	The alternative text for the image.
`title?: string`	An optional title shown for the image.


`static async booleanMatches`	Checks if the specified nullable boolean value matches the given value.
Parameters
value: boolean \| null \| Promise<boolean \| null>	The nullable boolean value to check, or a Promise resolving to the nullable boolean value.
pattern: boolean \| null	The boolean the value is expected to match. If 'pattern' is 'null', the value is expected to be 'null'.
Returns
Promise<boolean>	Whether the value matches the pattern.


`async getColumnWidth`	Gets the cell's width in 'px' (with padding).
Returns
Promise<number>	The cell's width.


`async getText`	Gets the cell's text.
Returns
Promise<string>	The cell's text.


`async getCells`	Gets a list of 'MatRowCellHarness', 'MatHeaderCellHarness' or 'MatFooterCellHarness' for all cells in the row.
filter: CellHarnessFilters = {}	A set of criteria that can be used to filter a list of cell harness instances.
Returns
Promise<Cell[]>	A filtered list of MatRowCellHarness for the cells in the row.


`async getColumnName`	Gets the name of the column that the cell belongs to.
Returns
Promise<string>	The name of the column that the cell belongs to.


`async getCellTextByColumnName`	Gets the text inside the row organized by columns.
Returns
Promise<MatRowHarnessColumnsText>	The text inside the row organized by columns.


`async getCellTextByIndex`	Gets the text of the cells in the row.
Parameters
filter: CellHarnessFilters = {}	A set of criteria that can be used to filter a list of cell harness instances.
Returns
Promise<string[]>	The text of the cells in the row.


`static async rowCellsContentMatch`	Checks if the values of the table row columns given in the 'value' parameter, match the given column values. Only columns defined in the pattern are inspected.
Parameters
value: MatRowHarnessColumnsText \| Promise \| null	The nullable object defining all columns of a row and their values used for the checks. Alternatively a Promise resolving to the nullable object.
pattern: Record<string, string \| RegExp> \| null	Object defining the columns and the values or RegExp expected to match. If 'pattern' is 'null', the value is expected to be 'null'.
Returns
Promise<boolean>	Whether the value matches the pattern.

Name	Description
`static hostSelector: '.mat-datatable'`	The selector for the host element of a 'MatDatatableHarness'.


`async getAllChildLoaders`	Gets an array of HarnessLoader instances.
Parameters
selector: string	A string used for selecting the instances.
Returns
Promise<HarnessLoader[]>	An array of HarnessLoader instances.


`async getAllHarnesses`	Gets an array of harness instances.
Parameters
query: HarnessQuery	A query for a ComponentHarness used to filter the instances, which is expressed as either a ComponentHarnessConstructor or a HarnessPredicate.
Returns
Promise<T[]>	An array of harness instances.


`async getCellTextByColumnName`	Gets the text inside the entire table organized by columns.
Returns
Promise<MatDatatableHarnessColumnsText>	The text inside the entire table organized by columns.


`async getChildLoader`	Searches for an element matching the given selector below the root element of this HarnessLoader.
Parameters
selector: string	A string used for selecting the HarnessLoader.
Returns
Promise<HarnessLoader>	A new HarnessLoader rooted at the first matching element.


`async getFooterRows`	Gets a list of the footer rows in a mat-datatable.
Returns
Promise<MatHeaderRowHarness[]>	A list of the footer rows.


`async getHarness`	Searches for an instance of the given ComponentHarness class or HarnessPredicate below the root element of this HarnessLoader.
Parameters
query: HarnessQuery	A query for a ComponentHarness used to filter the instances, which is expressed as either a ComponentHarnessConstructor or a HarnessPredicate.
Returns
Promise<T>	An instance of the harness corresponding to the first matching element.


`async getHarnessOrNull`	Gets an instance of the given ComponentHarness class or HarnessPredicate below the root element of this HarnessLoader.
Parameters
query HarnessQuery	A query for a ComponentHarness used to filter the instances, which is expressed as either a ComponentHarnessConstructor or a HarnessPredicate.
Returns
Promise<T \| null>	An instance of the harness corresponding to the first matching element.


`async getHeaderRows`	Gets a list of the header rows in a mat-datatable.
Returns
Promise<MatHeaderRowHarness[]>	A list of the header rows.


`async getRows`	Gets a list of the regular data rows in a mat-datatable.
Parameters
filter: RowHarnessFilters = {}	A set of criteria that can be used to filter a list of row harness instances.
Returns
Promise<MatRowHarness[]>	A filtered list of the regular data rows.


`async hasHarness`	Check, if the harness contains the instances defined by 'query'.
Parameters
query HarnessQuery	A query for a ComponentHarness used to filter the instances, which is expressed as either a ComponentHarnessConstructor or a HarnessPredicate.
Returns
Promise<boolean>	'True', if the instances is part of the harness.


`async host`	Gets a Promise for the 'TestElement' representing the host element of the component.
Returns
Promise<TestElement>	The 'TestElement' representing the host element of the component.


`static with`	Gets a 'HarnessPredicate' that can be used to search for a mat-datatable with specific attributes.
Parameters
options: TableHarnessFilters = {}	Options for narrowing the search.
Returns
HarnessPredicate	A 'HarnessPredicate' configured with the given options.


`static hostSelector: '.mat-mdc-footer-row'`	Used to identify the host element of a 'MatFooterRowHarness' instance.


`async getText`	Gets the header cell's text.
Return
Promise<string>	The header cell's text.


`async isResizable`	Check, if the cell is defined as 'resizable'.
Returns
Promise<boolean>	The cell is resizable.