In Angular Material, how does a `mat-table` build its rows from `matColumnDef`, `matHeaderRowDef` and `matRowDef`?
answer
- columns are offered, rows choose
- header and cell templates per column
- a string array sets order
- a plain array is not watched
- mat-table builds on CdkTable
basics
~20 sEach matColumnDef names a column and holds its header and cell templates. The header and data row definitions take a list of column names that decides which columns render and in what order, and the table stamps one data row per item.
solid answer
~40 sA `mat-table` is assembled from definitions, not markup. Each `<ng-container matColumnDef="stock">` gives a column a unique name and holds a `*matHeaderCellDef` template and a `*matCellDef="let item"` template. The rows then pick columns: `*matHeaderRowDef="columns"` and `*matRowDef="let item; columns: columns"` take an array of names, so the array decides which defined columns appear and in what order, and you can reorder or hide columns by changing it. The data comes from the `dataSource` input, which accepts an array, an Observable or a `DataSource`. A plain array is not watched for mutations, so after a `push` you call `renderRows()` or bind a new array. `MatTable` extends the CDK's `CdkTable` and adds Material styling and `mat-` selectors.
code
ts · 30 linesimport {Component, signal} from '@angular/core';
import {MatTableModule} from '@angular/material/table';
interface Sku { sku: string; name: string; stock: number; }
@Component({
selector: 'app-stock-list',
imports: [MatTableModule],
template: `
<table mat-table [dataSource]="items()" [trackBy]="bySku" aria-label="Warehouse stock">
<ng-container matColumnDef="sku">
<th mat-header-cell *matHeaderCellDef>SKU</th>
<td mat-cell *matCellDef="let item">{{ item.sku }}</td>
</ng-container>
<ng-container matColumnDef="stock">
<th mat-header-cell *matHeaderCellDef>On hand</th>
<td mat-cell *matCellDef="let item">{{ item.stock }}</td>
</ng-container>
<tr mat-header-row *matHeaderRowDef="columns"></tr>
<tr mat-row *matRowDef="let item; columns: columns" [class.low]="item.stock < 5"></tr>
</table>
`,
})
export class StockList {
readonly columns = ['sku', 'stock'];
readonly items = signal<Sku[]>([]);
readonly bySku = (_: number, item: Sku) => item.sku;
receive(item: Sku) { this.items.update(list => [...list, item]); }
}go deeper
Recall the three pieces: column definitions with header and cell templates, a header row and a data row that each take an array of column names, and a dataSource the table repeats rows for.
Explain that the column array, not definition order, controls what renders, why a mutated array needs renderRows(), and what array, Observable and DataSource inputs each give you.
Show you can drive dynamic columns from state, add trackBy for stable rows on refetch, and know which behaviour lives in CdkTable so you can reason about it without Material styles.
Weigh mat-table against CdkTable for a product with its own design language: shared behaviour and data-source contract versus the cost of carrying and overriding Material's table styles.
## The idea: definitions, then a column list Angular Material's table does not ask you to write `<tr>` and `<td>` for each item. You **declare** what each column looks like once, then tell the rows **which columns to show**. The table repeats the data row for every item it receives. This split is what makes columns easy to reorder, hide or add at run time. | Piece | Where it goes | What it does | |---|---|---| | `matColumnDef="name"` | an `<ng-container>` inside the table | registers a column under a unique name | | `*matHeaderCellDef` | inside the column | template for that column's header cell | | `*matCellDef="let item"` | inside the column | template for that column's data cell; `item` is the row's data object | | `*matFooterCellDef` | inside the column (optional) | template for a footer cell | | `*matHeaderRowDef="cols"` | a `<tr mat-header-row>` | renders the header row with the named columns | | `*matRowDef="let item; columns: cols"` | a `<tr mat-row>` | the template repeated once per data item | ## A warehouse inventory table For a stock screen listing SKUs, the component holds `columns = ['sku', 'name', 'stock']` and the template defines three columns. The header row and the data row both receive `columns`. Two rules follow from this design: - The **column list decides order**, not the order in which you wrote the `matColumnDef` blocks. `['stock', 'sku']` shows stock first and leaves `name` defined but hidden. - You do **not** have to list every defined column. Defining a column only makes it available. - Any content you place **inside** the `<tr mat-row>` element is ignored. The cells come from the column templates. - Bindings on the row element apply to every row, so `(click)="open(item)"` or `[class.low]="item.stock < 5"` on the `<tr mat-row>` work per item. - Each cell gets a class from its column name, `mat-column-stock`, which is how you right-align a numeric column for header and body at once. If a row's column list names a column that has no definition, the table throws an error naming the missing column id. Two columns defined with the same name also throw. ## How data reaches the table The `dataSource` input accepts three shapes: 1. **A plain array.** The simplest. The table renders it once and does **not** check it for changes on its own. If you `push`, `splice` or reorder the same array, call the table's `renderRows()` method, or assign a new array so the input itself changes. 2. **An Observable of arrays.** Every emission re-renders the rows, which suits data that arrives over time. 3. **A `DataSource` object.** A class with `connect()` and `disconnect()`. The table calls `connect()` to get an Observable of the rows to show and `disconnect()` when it is destroyed. This is where sorting, filtering, paging and fetching usually live; Material ships one ready-made implementation, `MatTableDataSource`. The `trackBy` input works like `trackBy` on Angular's older `ngFor`: give it a function that returns a stable id, such as the SKU, and the table keeps a row's DOM when the data object behind it is replaced. ## Where the CDK fits `MatTable` **extends** `CdkTable` from `@angular/cdk/table`. The CDK table carries all of the behaviour above (column and row definitions, data sources, sticky positioning, multiple row templates) with `cdk-` prefixed selectors and no visual opinion. Material's version swaps in `mat-` selectors and Material Design styles. That is why most `CdkTable` knowledge transfers directly, and why a team building its own design language can drop to `CdkTable` and style it from scratch. There are two template forms. `<table mat-table>` uses native table elements; `<mat-table>` with `<mat-row>` and `<mat-cell>` uses a `display: flex` layout instead, which gives up native features such as `colspan` and content-sized columns. ## Common mistakes - Expecting every defined column to render automatically. - Putting `<td>` elements inside the `<tr mat-row>` and wondering why they never appear. - Mutating a bound array and expecting the table to notice. - Assuming a column's name must equal the property it displays. The cell template decides what is shown; the name matters for the column list, the `mat-column-*` class, and the default sorting of `MatTableDataSource`. - Forgetting `MatTableModule` (or the individual directives) in the standalone component's `imports`, which leaves the attributes inert.
- What does an Angular Material table do when its row definition lists a column name that has no matColumnDef?It throws an error that names the missing column id, for example after a typo in the `columns` array or a column renamed in the template but not in the component. A duplicate `matColumnDef` name throws as well. Both surface as soon as the table renders, so a quick render test catches them.
- How would you let a warehouse user hide the bin column and move stock to the front without touching the template?Keep every `matColumnDef` in the template and make the displayed-columns array state, for example a signal, bound to both `*matHeaderRowDef` and `*matRowDef`. Removing `'bin'` from the array hides it; reordering the array reorders the columns. The definitions stay as a catalogue of what can be shown.
- Why might a team use the CDK's CdkTable instead of mat-table?`CdkTable` has the same column and row definitions, data-source contract and sticky support, with `cdk-` selectors and no Material styling. A team with its own visual language uses it to keep the behaviour while owning every pixel, rather than overriding Material's table styles.
- Every matColumnDef renders automatically, in the order it is written.
- Cells go inside the tr mat-row element, like a hand-written table.
- mat-table watches its bound array, so push shows the new row.
- A column's name must match the data property it displays.
- MatTable is a separate implementation with no relation to the CDK table.