angular/components · error

mat-grid-list: must pass in number of columns. Example: <mat

Error message

mat-grid-list: must pass in number of columns. Example: <mat-grid-list cols="3">

What it means

mat-grid-list requires the cols input to know how many columns to lay tiles out into. ngOnInit calls _checkCols and throws this friendly dev-mode error when cols is missing, zero, or falsy.

Source

Thrown at src/material/grid-list/grid-list.ts:133

  }

  ngOnInit() {
    this._checkCols();
    this._checkRowHeight();
  }

  /**
   * The layout calculation is fairly cheap if nothing changes, so there's little cost
   * to run it frequently.
   */
  ngAfterContentChecked() {
    this._layoutTiles();
  }

  /** Throw a friendly error if cols property is missing */
  private _checkCols() {
    if (!this.cols && (typeof ngDevMode === 'undefined' || ngDevMode)) {
      throw Error(
        `mat-grid-list: must pass in number of columns. ` + `Example: <mat-grid-list cols="3">`,
      );
    }
  }

  /** Default to equal width:height if rowHeight property is missing */
  private _checkRowHeight(): void {
    if (!this._rowHeight) {
      this._setTileStyler('1:1');
    }
  }

  /** Creates correct Tile Styler subtype based on rowHeight passed in by user */
  private _setTileStyler(rowHeight: string): void {
    if (this._tileStyler) {
      this._tileStyler.reset(this);
    }

View on GitHub (pinned to 0411926e7d)

Solutions

1. Add the cols attribute: <mat-grid-list cols="3">.
2. Guard the rendering until the column count is known: *ngIf="cols" around the grid or the host component.
3. Provide a fallback in the binding: [cols]="cols || 3".
4. Initialize the component property that feeds [cols] to a valid number > 0.

Example fix

// before
<mat-grid-list [rowHeight]="'1:1'" [cols]="numCols">
// after
<mat-grid-list [rowHeight]="'1:1'" [cols]="numCols || 4" *ngIf="numCols">
  <!-- tiles -->
</mat-grid-list>

// in the component before rendering
get safeCols(): number { return this.cols && this.cols > 0 ? this.cols : 4; }
// template: <mat-grid-list [cols]="safeCols">

function hasValidCols(cols: unknown): cols is number {
  return typeof cols === 'number' && Number.isInteger(cols) && cols > 0;
}

When it happens

Trigger: Using <mat-grid-list> without the cols attribute, with cols="" , cols bound to an undefined/null/0 variable (e.g. [cols]="columnCount" where columnCount is undefined at first render).

Common situations: Binding cols to an async value that hasn't resolved yet; forgetting the attribute when hand-writing the component; renaming a component variable without updating the binding; SSR/first-change timing where data arrives after ngOnInit.

Related errors

• A mat-tab-nav-panel must be specified via [tabPanel].
• Cannot specify both the `options` and `interval` inputs at t
• Value of `options` input cannot be an empty array
• MatTimepicker can only be registered with one input at a tim
• matBadge must be attached to an element node.

AI-assisted analysis of angular/components@0411926e7d (2026-08-31). Data as JSON: /api/errors/0a0d79260a819a92. Report an issue: GitHub.