---
title: "Overlays (legacy)"
framework: javascript
version: "36.1.0"
---

# Overlays (legacy)

Overlays are used for displaying messages over the top of the grid. There are two built-in overlays: loading and no-rows.

> **Warning**
>
> This page documents the legacy approach to handling overlays. For the latest documentation, see [Overlays Overview](https://www.ag-grid.com/javascript-data-grid/overlays-overview/).

## Loading overlay

Show or hide the loading overlay by setting the `loading` property to `true` or `false`.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `loading` | `boolean` |  | `undefined` | Show or hide the loading overlay. - `true`: the loading overlay is shown. - `false`: the loading overlay is hidden. - `undefined`: the grid will automatically show the loading overlay until `rowData` and `columnDefs` are provided. (Client Side Row Model only) |

The loading overlay takes precedence over the no-rows overlay and is not dependent of the state of `rowData`.

#### Loading overlay

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([ClientSideRowModelModule]);

interface IAthlete {
  athlete: string;
  country: string;
}

let gridApi: GridApi<IAthlete>;

const gridOptions: GridOptions<IAthlete> = {
  loading: true,
  columnDefs: [{ field: "athlete" }, { field: "country" }],
};

function setLoading(value: boolean) {
  gridApi!.setGridOption("loading", value);
}

function onBtnClearRowData() {
  gridApi!.setGridOption("rowData", []);
}

function onBtnSetRowData() {
  gridApi!.setGridOption("rowData", [
    { athlete: "Michael Phelps", country: "US" },
  ]);
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setLoading = setLoading;
  (<any>window).onBtnClearRowData = onBtnClearRowData;
  (<any>window).onBtnSetRowData = onBtnSetRowData;
}
```

[Live example: Loading overlay](https://www.ag-grid.com/examples/overlays/loading-overlay/typescript)

## No rows overlay

When `rowData` is set to an empty array `[]`, the grid automatically displays the no-rows overlay. The no-rows overlay can also be programmatically shown / hidden via the grid API.

> **Warning**
>
> It is recommended to use the [Active Overlay](https://www.ag-grid.com/javascript-data-grid/overlays-active/) to manually display an overlay.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `showNoRowsOverlay` | `Function` |  |  | Show the no-rows overlay. If `loading` is true, this will not do anything. - **Prefer `setGridOption('activeOverlay', 'agNoRowsOverlay')` .** |
| `hideOverlay` | `Function` |  |  | Hide the no-rows overlay if it is showing. - **Prefer `setGridOption('activeOverlay', undefined)` .** |

The automatic displaying of the no-rows overlay can be suppressed by setting `suppressNoRowsOverlay` to `true`.

#### No Rows Overlay

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([ClientSideRowModelModule]);

interface IAthlete {
  athlete: string;
  country: string;
}

let gridApi: GridApi<IAthlete>;

const gridOptions: GridOptions<IAthlete> = {
  rowData: [],
  columnDefs: [{ field: "athlete" }, { field: "country" }],
};

function onBtnClearRowData() {
  gridApi!.setGridOption("rowData", []);
}

function onBtnSetRowData() {
  gridApi!.setGridOption("rowData", [
    { athlete: "Michael Phelps", country: "US" },
  ]);
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).onBtnClearRowData = onBtnClearRowData;
  (<any>window).onBtnSetRowData = onBtnSetRowData;
}
```

[Live example: No Rows Overlay](https://www.ag-grid.com/examples/overlays/no-rows-overlay/typescript)

## Initial loading overlay

If `loading` is not explicitly defined, the grid will automatically show the loading overlay until both `rowData` and `columnDefs` are provided with a non-null value for the first time. This behaviour can be suppressed by initialising the grid with an appropriate `loading` state.

## Customisation

Overlays can be customised by providing either a HTML string or custom component via grid properties.

### Custom Loading Overlay

The loading overlay can be customised via the grid properties `overlayLoadingTemplate` or `loadingOverlayComponent` and `loadingOverlayComponentParams`.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `overlayLoadingTemplate` | `string` |  |  | Provide a HTML string to override the default loading overlay. Supports non-empty plain text or HTML with a single root element. - **Prefer `overlayComponent` / `overlayComponentSelector`** |
| `loadingOverlayComponent` | `any` |  |  | Provide a custom loading overlay component. - **Prefer `overlayComponent` / `overlayComponentSelector`** |
| `loadingOverlayComponentParams` | `any` |  |  | Customise the parameters provided to the loading overlay component. - **Prefer using `overlayComponentParams`** |

Implement this interface to provide a custom overlay when data is being loaded.

```ts

interface ILoadingOverlayComp&lt;TData = any, TContext = any&gt; {
  // Return the DOM element of your component, this is what the grid puts into the DOM 
  getGui(): <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement" target="_blank" rel="noreferrer">HTMLElement</a>;

  // Gets called once by grid when the component is being removed; if your component needs to do any cleanup, do it here 
  destroy?(): void;

  // The init(params) method is called on the component once. 
  init?(params: TParams): AgPromise<<span/>void>  |  void;

  // Gets called when the `overlayComponentParams` grid option is updated
  refresh?(params: TParams): void;

}
```

This example demonstrates how to provide a custom loading overlay component customised via parameters.

#### Custom Loading Overlay Components

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  GridApi,
  GridOptions,
  ModuleRegistry,
  TextEditorModule,
  TextFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { CustomLoadingOverlay } from "./customLoadingOverlay";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  TextEditorModule,
  TextFilterModule,
  ClientSideRowModelModule,
]);

interface IAthlete {
  athlete: string;
  country: string;
}

const columnDefs: ColDef[] = [
  { field: "athlete", width: 150 },
  { field: "country", width: 120 },
];

const rowData: IAthlete[] = [
  { athlete: "Michael Phelps", country: "United States" },
  { athlete: "Natalie Coughlin", country: "United States" },
  { athlete: "Aleksey Nemov", country: "Russia" },
  { athlete: "Alicia Coutts", country: "Australia" },
];

let gridApi: GridApi<IAthlete>;

const gridOptions: GridOptions<IAthlete> = {
  defaultColDef: {
    editable: true,
    flex: 1,
    minWidth: 100,
    filter: true,
  },

  loading: true,

  columnDefs: columnDefs,
  rowData,

  loadingOverlayComponent: CustomLoadingOverlay,
  loadingOverlayComponentParams: {
    loadingMessage: "One moment please...",
  },
};

function setLoading(value: boolean) {
  gridApi!.setGridOption("loading", value);
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setLoading = setLoading;
}
```

[Live example: Custom Loading Overlay Components](https://www.ag-grid.com/examples/overlays/custom-overlay-loading/typescript)

### Custom No Rows Overlay

The no-rows overlay can be customised via the grid properties `overlayNoRowsTemplate` or `noRowsOverlayComponent` and `noRowsOverlayComponentParams`.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `overlayNoRowsTemplate` | `string` |  |  | Provide a HTML string to override the default no-rows overlay. Supports non-empty plain text or HTML with a single root element. - **Prefer `overlayComponent` / `overlayComponentSelector`** |
| `noRowsOverlayComponent` | `any` |  |  | Provide a custom no-rows overlay component. - **Prefer `overlayComponent` / `overlayComponentSelector`** |
| `noRowsOverlayComponentParams` | `any` |  |  | Customise the parameters provided to the no-rows overlay component. - **Prefer using `overlayComponentParams`** |

Implement this interface to provide a custom overlay when no-rows loaded.

```ts

interface INoRowsOverlayComp&lt;TData = any, TContext = any&gt; {
  // Return the DOM element of your component, this is what the grid puts into the DOM 
  getGui(): <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement" target="_blank" rel="noreferrer">HTMLElement</a>;

  // Gets called once by grid when the component is being removed; if your component needs to do any cleanup, do it here 
  destroy?(): void;

  // The init(params) method is called on the component once. 
  init?(params: TParams): AgPromise<<span/>void>  |  void;

  // Gets called when the `overlayComponentParams` grid option is updated
  refresh?(params: TParams): void;

}
```

This example demonstrates how to provide a custom no-rows overlay component customised via parameters.

#### Custom No Rows Overlay Components

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  GridApi,
  GridOptions,
  ModuleRegistry,
  TextEditorModule,
  TextFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { CustomNoRowsOverlay } from "./customNoRowsOverlay";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  TextEditorModule,
  TextFilterModule,
  ClientSideRowModelModule,
]);

interface IAthlete {
  athlete: string;
  country: string;
}

const columnDefs: ColDef[] = [
  { field: "athlete", width: 150 },
  { field: "country", width: 120 },
];

let gridApi: GridApi<IAthlete>;

const gridOptions: GridOptions<IAthlete> = {
  defaultColDef: {
    editable: true,
    flex: 1,
    minWidth: 100,
    filter: true,
  },

  columnDefs: columnDefs,
  rowData: [],

  noRowsOverlayComponent: CustomNoRowsOverlay,
  noRowsOverlayComponentParams: {
    noRowsMessageFunc: () =>
      "No rows found at: " + new Date().toLocaleTimeString(),
  },
};

function onBtnClearRowData() {
  gridApi!.setGridOption("rowData", []);
}

function onBtnSetRowData() {
  gridApi!.setGridOption("rowData", [
    { athlete: "Michael Phelps", country: "US" },
  ]);
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).onBtnClearRowData = onBtnClearRowData;
  (<any>window).onBtnSetRowData = onBtnSetRowData;
}
```

[Live example: Custom No Rows Overlay Components](https://www.ag-grid.com/examples/overlays/custom-overlay-no-rows/typescript)