simple-table

A reusable, declarative Angular Material data table built with Angular 21. Configure columns with a JSON array, get sorting, multi-select, dropdown filters, pagination, sticky columns, row actions, theming, and dark mode out of the box — with an escape hatch for custom cell templates. Zero third-party dependencies beyond Angular Material.

Live demo	ng-simple-table.vercel.app
npm	ngx-mat-simple-table
Source	github.com/xonaib/ng-simple-table

Screenshots

Why

Most Angular Material table examples require you to write <ng-container matColumnDef> blocks for every column. This component flips that: you describe your columns as data, and the table renders itself. You only drop down to a template when a cell needs custom markup.

Each column is identified by a key string: it is both the matColumnDef id Material uses internally and the property name read for default cell text (row[key]), so it stays aligned with your row type.

Features

Feature	Notes
Declarative columns	Pass a ColumnDef[] array — no per-column template boilerplate
Sorting	MatSort on data columns; sortable defaults to true — set sortable: false to opt out
Row selection	Multi-select checkboxes, master toggle, selectionChange output
Dropdown column filters	Distinct values built from dataSource; Apply/Clear emits (filterChange)
Pagination	MatPaginator with configurable page sizes; server- and client-side modes
Unknown-total pagination	Omit [length] in server-side mode — next/prev inferred automatically from page row count
Declarative actions	TableAction[] with five position slots: toolbar, above, below, row-inline, row-menu
Sticky columns	ColumnDef.sticky: 'left' | 'right' — pins columns to either edge; drag-reorder is disabled for sticky columns
Fill-container height	TableConfig.fillContainer: true — table expands to fill its parent; toolbar and paginator always stay in view
Column widths	Optional width on ColumnDef (number = px, string = CSS). Resize overrides at runtime
Column reorder	CDK drag-drop on header cells and in the column-chooser menu
Column chooser	Show/hide columns and reorder via toolbar menu with responsive max-height
Column resize	Drag handles on header cells; (columnWidthChange) emits Record<string, number>
displayValue	Per-column (value, row) => string transform for formatting or derived display text
cellClass	Per-column (value, row) => string | string[] for conditional cell styling (status badges, colour-coded priority, etc.)
Custom cell templates	cellDef attribute on <ng-template> — value must match the column key
State persistence	StStateStoringDirective saves column order, visibility, and widths to localStorage
Export to Excel	StExportDirective with full XLSX via ExcelJS; export all records via allDataProvider
Virtual scroll	TableConfig.virtual: true — renders only visible rows via CdkVirtualScrollViewport; works in client-side and server-side modes
CSS theming	22 --st-* custom properties for colours, borders, font, row height, scrollbar, and sticky cells
Dark mode	Set body { color-scheme: dark } — all --st-* tokens and Angular Material tokens flip automatically
OnPush + signals	ChangeDetectionStrategy.OnPush throughout; zero ChangeDetectorRef usage

Setup

npm install ngx-mat-simple-table

Add provideHttpClient() to your app.config.ts if not already present.

Quick start

import {
  SimpleTableComponent,
  CellDefDirective,
  ColumnDef,
  FilterType,
  TableConfig,
} from 'ngx-mat-simple-table';

columns: ColumnDef[] = [
  { key: 'select' },
  { key: 'id',     label: 'ID',     width: 72,  sticky: 'left' },
  { key: 'name',   label: 'Name',   width: 220, sticky: 'left' },
  {
    key: 'status',
    label: 'Status',
    hasColumnFilters: true,
    filterType: FilterType.DropDown,
    displayValue: v => String(v).toUpperCase(),
    cellClass:    v => `status-${v}`,
  },
  { key: 'priority', label: 'Priority', hasColumnFilters: true, filterType: FilterType.DropDown },
  { key: 'dueDate',  label: 'Due Date' },
];

tableConfig: TableConfig = {
  isPaginated: true,
  paginationOptions: { defaultPageSize: 25, pageSizeOptions: [10, 25, 50] },
  horizontalScroll: true,
  fillContainer: true,
};

<simple-table
  [dataSource]="pagedItems"
  [tableColumns]="columns"
  [tableConfig]="tableConfig"
  [length]="totalCount"
  [stickyHeaders]="true"
  (page)="onPage($event)"
  (sortChange)="onSort($event)"
  (filterChange)="onFilter($event)"
  (selectionChange)="onSelect($event)"
>
</simple-table>

Custom cell templates

When a cell needs more than plain text — a link, a badge, a chip — add an <ng-template> with the cellDef attribute set to the same string as the column key.

<simple-table [dataSource]="items" [tableColumns]="columns" ...>
  <ng-template cellDef="name" let-row>
    <a [routerLink]="['/items', row.id]">{{ row.name }}</a>
  </ng-template>

  <ng-template cellDef="status" let-row>
    <span [class]="'badge badge-' + row.status">{{ row.status }}</span>
  </ng-template>
</simple-table>

Tip: cellClass on ColumnDef handles most styling-only cases without a template — reserve cellDef for when you need actual HTML structure.

Column definition (ColumnDef)

Property	Type	Description
key	string	Required. Column id and default row[key] field. Use 'select' for the checkbox column.
label	string	Header text. Title-cased from key if omitted.
width	number | string	Optional width (number = px; string = any CSS length). Omitted = auto.
sticky	'left' | 'right'	Pin column to an edge. Drag-reorder is disabled for sticky columns.
sortable	boolean	Set false to disable sorting. Omitted = sortable. select is never sortable.
hasColumnFilters	boolean	Shows the filter icon and builds a dropdown from distinct values.
filterType	FilterType	FilterType.DropDown — checkbox list with search.
displayValue	(value, row) => string	Transform the displayed cell text (formatting, derived values).
cellClass	(value, row) => string | string[] | null	Return a CSS class or array of classes to apply to the body cell.

Reserved key: st-layout-filler is used internally — do not use it as a column key.

Table config (TableConfig)

Property	Type	Default	Description
isPaginated	boolean	false	Show MatPaginator.
paginationOptions	PaginationOptions	—	defaultPageSize and pageSizeOptions.
clientSide	boolean	false	Hand sorting, filtering, and pagination to an internal MatTableDataSource.
horizontalScroll	boolean	false	Enable horizontal scroll on the table wrapper.
fillContainer	boolean	false	Stretch the table to fill its parent height; toolbar and paginator stay in view.
showColumnChooser	boolean	true	Show the column-chooser button in the toolbar.
showRefresh	boolean	true	Show the refresh button in the toolbar.
columnDraggable	boolean	true	Enable column drag-reorder.
columnResizable	boolean	true	Enable column resize handles.
maxHeight	string	—	CSS max-height on the scroll wrapper (ignored when fillContainer is true).
virtual	boolean	false	Enable virtual scrolling. Replaces the paginator with a CdkVirtualScrollViewport that only renders visible rows. Requires a defined height — use fillContainer: true or maxHeight.
virtualRowHeight	number	48	Pixel height of each data row. Must match the actual rendered row height (same as --st-row-height).

Inputs

Input	Type	Default	Description
dataSource	T[] | Observable<T[]>	—	Row data. Required.
tableColumns	ColumnDef[]	—	Column definitions. Required.
tableConfig	TableConfig	{}	Pagination, scroll, toolbar, drag/resize flags.
tableId	string	—	Unique key for StStateStoringDirective persistence.
length	number	0	Total row count for the paginator (server-side).
pageIndex	number	—	Sync paginator when the host resets the page (server-side).
selectedRows	T[]	—	Pre-select rows programmatically.
stickyHeaders	boolean	false	Sticky header row.
virtualOffset	number	0	Server-side virtual scroll only. The absolute row index (0-based) of the first row in dataSource. See Virtual scroll — server-side.

Outputs

Output	Payload	Description
page	PageEvent	Page or page-size change.
sortChange	Sort	Column sort changed.
filterChange	Map<string, ItemParent>	Apply or Clear (map keys = column key).
selectionChange	T[]	Selected rows.
refresh	void	Refresh toolbar button clicked.
columnOrderChange	string[]	Data column keys after header drag-reorder.
columnWidthChange	Record<string, number>	Column widths in px after resize.
virtualRangeChange	VirtualRange	Server-side virtual scroll only. Emits { start, end } as the user scrolls — the host should fetch that window and update [dataSource], [virtualOffset], and [length].

Theming

Override any --st-* property on the <simple-table> element or any ancestor:

simple-table {
  --st-header-bg:       #1e293b;
  --st-header-color:    #f1f5f9;
  --st-border-color:    #334155;
  --st-row-hover-bg:    #0f172a;
  --st-row-selected-bg: #1e3a5f;
  --st-sticky-cell-bg:  #1a2535;
  --st-cell-color:      #e2e8f0;
  --st-row-bg:          transparent;
  --st-font-size:       13px;
  --st-row-height:      44px;
  --st-toolbar-bg:      #0f172a;
}

Token	Default	Controls
--st-header-bg	surface-variant	Header row background
--st-header-color	on-surface-variant	Header row text
--st-border-color	outline-variant	All cell and toolbar borders
--st-row-bg	transparent	Default body row background
--st-row-hover-bg	surface-container-low	Hovered row background
--st-row-selected-bg	secondary-container	Selected row background
--st-sticky-cell-bg	surface-container	Body cells in sticky columns
--st-cell-color	on-surface	Body cell text colour
--st-font-size	14px	Body cell font size
--st-row-height	48px	Row min-height
--st-toolbar-bg	surface	Toolbar background
--st-scrollbar-width	thin	Scrollbar width (thin | auto | none)
--st-scrollbar-thumb	outline	Scrollbar thumb colour
--st-scrollbar-track	transparent	Scrollbar track colour
--st-chooser-max-height	320px	Column chooser list max-height before scroll
--st-filter-popup-bg	surface	Filter dropdown background
--st-filter-popup-border	outline-variant	Filter dropdown border
--st-filter-header-bg	surface-variant	Filter dropdown header strip
--st-filter-header-color	on-surface-variant	Filter dropdown header text
--st-filter-footer-bg	surface-variant	Filter dropdown footer strip
--st-filter-footer-border	outline-variant	Filter dropdown footer top border
--st-filter-input-bg	surface	Filter search input background
--st-filter-input-border	outline	Filter search input border

Dark mode

All defaults alias Angular Material's --mat-sys-* tokens, so the full table adapts automatically when you switch color-scheme:

// toggle dark/light at runtime
document.body.style.colorScheme = 'dark'; // or 'light'

Use the CSS light-dark() function for any custom cell colours so they adapt too:

.status-done {
  background: light-dark(#dcfce7, #14532d);
  color:      light-dark(#15803d, #86efac);
}

Column filters

Set hasColumnFilters: true and filterType: FilterType.DropDown. The table builds a checkbox list per filterable column from distinct row[key] values in the current dataSource.

• Server-side: options reflect the current page only; stale selections are pruned on each fetch and (filterChange) re-emits automatically.
• Client-side: options span the full dataset.

Read ItemParent.selectedKeys in the (filterChange) handler for the active values.

Actions

Pass a TableAction<T>[] to [actions] to add buttons anywhere around the table without writing any extra template code.

import { TableAction } from 'ngx-mat-simple-table';

actions: TableAction<Task>[] = [
  // left side of the toolbar
  {
    id: 'add',
    label: 'New task',
    icon: 'add',
    position: 'toolbar',
    color: 'primary',
    variant: 'flat',
    cb: () => this.openCreateDialog(),
  },
  {
    id: 'bulk-delete',
    label: 'Delete selected',
    icon: 'delete_sweep',
    position: 'toolbar',
    color: 'warn',
    variant: 'stroked',
    disabled: () => this.selected().length === 0,
    cb: () => this.bulkDelete(this.selected()),
  },
  // icon button on every row (label omitted → icon-only with tooltip)
  {
    id: 'edit',
    icon: 'edit',
    position: 'row-inline',
    cb: (row) => this.openEditDialog(row),
  },
  // overflow menu on every row
  {
    id: 'delete',
    label: 'Delete',
    icon: 'delete',
    position: 'row-menu',
    color: 'warn',
    cb: (row) => this.deleteTask(row),
  },
  // left side of the paginator row
  {
    id: 'export-selected',
    label: 'Export selected',
    icon: 'file_download',
    position: 'below',
    disabled: () => this.selected().length === 0,
    cb: () => this.exportSelected(),
  },
];

<simple-table
  [dataSource]="tasks"
  [tableColumns]="columns"
  [tableConfig]="config"
  [actions]="actions"
  (selectionChange)="selected.set($event)"
>
</simple-table>

Action positions

Position	Where it renders
toolbar	Left side of the toolbar row, alongside the column-chooser and export icons
above	Same toolbar row, rendered before toolbar actions
below	Left side of the paginator row
row-inline	Icon button visible on every row in a sticky-end column
row-menu	Item inside the ⋯ overflow menu in the same sticky column

TableAction<T> properties

Property	Type	Description
id	string	Required. Unique key; used as track id.
position	ActionPosition	Required. Where the action renders.
cb	(row: T | undefined) => void	Required. Called on click. row is the clicked row for row positions, undefined otherwise.
label	string	Button label. Omit for an icon-only button (tooltip falls back to id).
icon	string	Material icon name.
variant	'flat' | 'stroked' | 'text' | 'icon'	Button style for non-row positions. Defaults to 'stroked'.
color	'primary' | 'accent' | 'warn'	Material button colour.
disabled	(row: T | undefined) => boolean	Return true to disable.

Unknown-total pagination

If your API doesn't return a total row count, omit [length]. The table infers next/prev availability from the number of rows returned: a full page enables the next button; a short page disables it. No extra configuration needed.

<simple-table
  [dataSource]="currentPage()"
  [pageIndex]="_pageIndex()"
  [tableColumns]="columns"
  [tableConfig]="config"
  (page)="onPage($event)"
>
</simple-table>

Virtual scroll

Set virtual: true in TableConfig to replace pagination with CdkVirtualScrollViewport. Only the rows visible in the viewport (plus a small buffer) are in the DOM, keeping rendering fast for large datasets.

Requirements:

• The table must have a defined height. Use fillContainer: true (recommended) or maxHeight.
• virtualRowHeight must equal the actual rendered row height in pixels (default 48, matching --st-row-height).

Client-side virtual scroll

Pass the entire dataset as dataSource. The table filters, sorts, and virtualises it internally — no additional wiring needed.

tableConfig: TableConfig = {
  virtual:          true,
  virtualRowHeight: 48,
  clientSide:       true,
  fillContainer:    true,
};

<simple-table
  [dataSource]="allRows"
  [tableColumns]="columns"
  [tableConfig]="tableConfig"
  [stickyHeaders]="true"
>
</simple-table>

Server-side virtual scroll

The table emits (virtualRangeChange) as the user scrolls. The host fetches the requested window from the server and passes it back with the window's absolute start index ([virtualOffset]) and the total row count ([length]).

tableConfig: TableConfig = {
  virtual:          true,
  virtualRowHeight: 48,
  fillContainer:    true,
};

// --- state in the host component ---
readonly rows         = signal<Row[]>([]);
readonly totalCount   = signal(0);
readonly windowOffset = signal(0);

onVirtualRangeChange(range: VirtualRange): void {
  // range.start / range.end are absolute indices into the full dataset.
  // Fetch the window from your API and update the signals.
  this.http.get<{ data: Row[]; total: number }>('/api/rows', {
    params: { offset: range.start, limit: range.end - range.start },
  }).subscribe(({ data, total }) => {
    this.rows.set(data);
    this.totalCount.set(total);
    this.windowOffset.set(range.start);
  });
}

<simple-table
  [dataSource]="rows()"
  [tableColumns]="columns"
  [tableConfig]="tableConfig"
  [length]="totalCount()"
  [virtualOffset]="windowOffset()"
  [stickyHeaders]="true"
  (virtualRangeChange)="onVirtualRangeChange($event)"
>
</simple-table>

How the table positions the window: Each row N in the full dataset sits at pixel N × virtualRowHeight from the top of the scroll container. When the host provides rows [offset … offset+n], the table sets margin-top: offset × virtualRowHeight on the content wrapper, placing those rows at exactly the right scroll position. length × virtualRowHeight drives the scrollbar height so the full range is scrollable immediately.

State persistence

Add <st-state-storing /> inside <simple-table> and provide a unique tableId:

<simple-table tableId="my-table" ...>
  <st-state-storing />
</simple-table>

Column order, visibility, and widths are saved to localStorage under that key and restored on next load. New columns added after a saved state are appended at the end rather than dropped.

Export

Add <st-export /> inside <simple-table>. For server-side tables, pass [allDataProvider] to fetch all records for export regardless of the current page:

<simple-table ...>
  <st-export [allDataProvider]="getAllForExport" />
</simple-table>

readonly getAllForExport = (): Promise<Row[]> =>
  firstValueFrom(this.http.get<{ data: Row[] }>('/api/rows').pipe(map(r => r.data)));

Running the project locally

Prerequisites

• Node.js 20+
• npm 10+

Clone and run

git clone https://github.com/xonaib/ng-simple-table.git
cd ng-simple-table
npm install
npm run build:lib   # build the library once before starting the demo
npm start           # opens http://localhost:4200

The demo runs against an in-memory interceptor — no backend required.

Library development

# In one terminal — rebuild the library on every change
npm run build:lib:watch

# In another terminal — serve the demo app
npm start

Changes to projects/ngx-mat-simple-table/ are picked up automatically; refresh the browser to see them.

Build for production

npm run build       # builds lib + demo app

Publishing the library

npm run publish:lib # runs build:lib then publishes dist/ngx-mat-simple-table to npm

Roadmap

v1.3

• TableConfig.scrollbarVisibility: 'auto' | 'always' | 'hover'
• Inline row editing
• Storybook stories
• Unit test suite

License

MIT

Blog Post

I got tired of copy-pasting the same Angular Material table setup, so I built a library — covers the build process, decisions, and what broke along the way.

---

Release Notes

v1.2.2

• Declarative actions API — TableAction<T>[] with five