overlay

The message over the rows: loading, an error, nothing to show.

Type	'loading' | 'error' | null
Default	null
Live update (update())	Yes
Angular	the [overlay] input
<dz-grid>	the overlay attribute
Declared in	packages/dom/src/settings.ts

What it does

Left out (or null), the grid decides by itself: « Loading… » while a server’s first rows are on their way, the error message when a server’s request failed, « No rows » when there are none, « No rows match the filters » when the filters or the search hide them all — and nothing otherwise. Under the error message, forced or not, a « Retry » button asks the rows again (a server’s: a new request).

'loading' and 'error' force one, whatever the rows: for an application that loads its rows itself and gives them with rows. Give null again once they are there. The texts are the bundle’s (grid.loading, grid.error, grid.noRows, grid.noMatches); a part can draw the overlay instead (slots()).

To say that rows on screen are being reloaded, without covering them, use busy.

Example

TypeScript

import { createGrid } from '@dzgrid/dom';
import { EN } from '@dzgrid/dom/locales/en';

type Station = { id: string; name: string; rain: number };

const grid = createGrid<Station>(document.getElementById('stations')!, {
  columns: [{ id: 'name', header: 'Station' }, { id: 'rain', header: 'Rain (mm)', type: 'number' }],
  getRowId: (s) => s.id,
  messages: EN,
  overlay: 'loading',
});

fetch('/api/stations')
  .then((r) => r.json() as Promise<Station[]>)
  .then((rows) => grid.update({ rows, overlay: null }))
  .catch(() => grid.update({ overlay: 'error' }));

Angular

import { Component, signal } from '@angular/core';
import { DzGrid, type DzgColumnOrGroup } from '@dzgrid/angular';
import { EN } from '@dzgrid/dom/locales/en';

type Station = { id: string; name: string; rain: number };

@Component({
  selector: 'app-stations',
  imports: [DzGrid],
  template: `<dz-grid [rows]="rows()" [columns]="columns" [getRowId]="rowId" [messages]="messages" [overlay]="overlay()" />`,
})
export class Stations {
  readonly rows = signal<Station[]>([]);
  readonly overlay = signal<'loading' | 'error' | null>('loading');
  readonly columns: DzgColumnOrGroup<Station>[] = [{ id: 'name', header: 'Station' }, { id: 'rain', header: 'Rain (mm)', type: 'number' }];
  readonly rowId = (s: Station) => s.id;
  readonly messages = EN;

  constructor() {
    fetch('/api/stations')
      .then((r) => r.json() as Promise<Station[]>)
      .then((rows) => (this.rows.set(rows), this.overlay.set(null)))
      .catch(() => this.overlay.set('error'));
  }
}

Web Component

<dz-grid overlay="loading"></dz-grid>

import '@dzgrid/element/define';
import type { DzGridElement } from '@dzgrid/element';
import { EN } from '@dzgrid/dom/locales/en';

type Station = { id: string; name: string; rain: number };

const grid = document.querySelector<DzGridElement<Station>>('dz-grid')!;
grid.columns = [{ id: 'name', header: 'Station' }, { id: 'rain', header: 'Rain (mm)', type: 'number' }];
grid.getRowId = (s) => s.id;
grid.messages = EN;
fetch('/api/stations')
  .then((r) => r.json() as Promise<Station[]>)
  .then((rows) => ((grid.rows = rows), grid.removeAttribute('overlay')))
  .catch(() => grid.setAttribute('overlay', 'error'));

Live demo

No overlay set and no rows: the grid says « No rows » by itself.

See also

• busy — rows reloaded and kept on screen.
• Server data — the overlays a server’s rows bring by themselves.