---
title: "Overlays (legacy)"
framework: react
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/react-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

```tsx
'use client';
import React, { StrictMode, useState } from "react";
import { createRoot } from "react-dom/client";

import {
  ClientSideRowModelModule,
  enableDevValidations,
} from "ag-grid-community";
import type { ColDef } from "ag-grid-community";
import { AgGridProvider, AgGridReact } from "ag-grid-react";

import "./styles.css";

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

const modules = [ClientSideRowModelModule];

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

const columnDefs: ColDef[] = [
  { field: "athlete", minWidth: 200 },
  { field: "country", minWidth: 200 },
];

const GridExample = () => {
  const [loading, setLoading] = useState(true);
  const [rowData, setRowData] = useState<IAthlete[] | undefined>();

  return (
    <AgGridProvider modules={modules}>
      <div className="example-wrapper">
        <div>
          <label className="checkbox">
            <input
              type="checkbox"
              onChange={(e) => setLoading(e.target.checked)}
              checked={loading}
            />
            loading
          </label>

          <button onClick={() => setRowData([])}>Clear rowData</button>
          <button
            onClick={() =>
              setRowData([{ athlete: "Michael Phelps", country: "US" }])
            }
          >
            Set rowData
          </button>
        </div>

        <div style={{ height: "100%" }}>
          <AgGridReact
            loading={loading}
            rowData={rowData}
            columnDefs={columnDefs}
          />
        </div>
      </div>
    </AgGridProvider>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(
  <StrictMode>
    <GridExample />
  </StrictMode>,
);
```

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

## 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/react-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

```tsx
"use client";

import React, {
  useCallback,
  useMemo,
  useRef,
  useState,
  StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgGridReact, AgGridProvider } from "ag-grid-react";
import "./styles.css";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  GridApi,
  GridOptions,
  ModuleRegistry,
  enableDevValidations,
} from "ag-grid-community";

if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

const modules = [ClientSideRowModelModule];

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

const GridExample = () => {
  const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
  const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
  const [rowData, setRowData] = useState<IAthlete[]>([]);
  const [columnDefs, setColumnDefs] = useState<ColDef[]>([
    { field: "athlete" },
    { field: "country" },
  ]);

  const onBtnClearRowData = useCallback(() => {
    setRowData([]);
  }, []);

  const onBtnSetRowData = useCallback(() => {
    setRowData([{ athlete: "Michael Phelps", country: "US" }]);
  }, []);

  return (
    <AgGridProvider modules={modules}>
      <div style={containerStyle}>
        <div className="example-wrapper">
          <div>
            <button onClick={onBtnClearRowData}>Clear rowData</button>
            <button onClick={onBtnSetRowData}>Set rowData</button>
          </div>

          <div style={gridStyle}>
            <AgGridReact<IAthlete> rowData={rowData} columnDefs={columnDefs} />
          </div>
        </div>
      </div>
    </AgGridProvider>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(
  <StrictMode>
    <GridExample />
  </StrictMode>,
);
```

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

## 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`** |

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

#### Custom Loading Overlay Components

```tsx
'use client';
import React, { StrictMode, useMemo, useState } from "react";
import { createRoot } from "react-dom/client";

import {
  ClientSideRowModelModule,
  TextEditorModule,
  TextFilterModule,
  enableDevValidations,
} from "ag-grid-community";
import type { ColDef } from "ag-grid-community";
import { AgGridProvider, AgGridReact } from "ag-grid-react";

import CustomLoadingOverlay from "./customLoadingOverlay";
import "./styles.css";

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

const modules = [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" },
];

const defaultColDef: ColDef = {
  editable: true,
  flex: 1,
  minWidth: 100,
  filter: true,
};

const GridExample = () => {
  const [loading, setLoading] = useState(true);

  const loadingOverlayComponentParams = useMemo(() => {
    return { loadingMessage: "One moment please..." };
  }, []);

  return (
    <AgGridProvider modules={modules}>
      <div className="example-wrapper">
        <div>
          <label className="checkbox">
            <input
              type="checkbox"
              onChange={(e) => setLoading(e.target.checked)}
              checked={loading}
            />
            loading
          </label>
        </div>

        <div style={{ height: "100%", width: "100%" }}>
          <AgGridReact<IAthlete>
            loading={loading}
            rowData={rowData}
            columnDefs={columnDefs}
            defaultColDef={defaultColDef}
            loadingOverlayComponent={CustomLoadingOverlay}
            loadingOverlayComponentParams={loadingOverlayComponentParams}
          />
        </div>
      </div>
    </AgGridProvider>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(
  <StrictMode>
    <GridExample />
  </StrictMode>,
);
```

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

### 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`** |

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

#### Custom No Rows Overlay Components

```tsx
'use client';
import React, { StrictMode, useMemo, useState } from "react";
import { createRoot } from "react-dom/client";

import type { ColDef } from "ag-grid-community";
import {
  ClientSideRowModelModule,
  TextEditorModule,
  TextFilterModule,
  enableDevValidations,
} from "ag-grid-community";
import { AgGridProvider, AgGridReact } from "ag-grid-react";

import CustomNoRowsOverlay from "./customNoRowsOverlay";
import "./styles.css";

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

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

const defaultColDef = {
  editable: true,
  flex: 1,
  minWidth: 100,
  filter: true,
};

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

const modules = [TextEditorModule, TextFilterModule, ClientSideRowModelModule];

const GridExample = () => {
  const [rowData, setRowData] = useState<IAthlete[]>([]);

  const noRowsOverlayComponentParams = useMemo(() => {
    return {
      noRowsMessageFunc: () =>
        "No rows found at: " + new Date().toLocaleTimeString(),
    };
  }, []);

  return (
    <AgGridProvider modules={modules}>
      <div className="example-wrapper">
        <div>
          <button onClick={() => setRowData([])}>Clear rowData</button>
          <button
            onClick={() =>
              setRowData([{ athlete: "Michael Phelps", country: "US" }])
            }
          >
            Set rowData
          </button>
        </div>

        <div style={{ height: "100%" }}>
          <AgGridReact<IAthlete>
            rowData={rowData}
            columnDefs={columnDefs}
            defaultColDef={defaultColDef}
            noRowsOverlayComponent={CustomNoRowsOverlay}
            noRowsOverlayComponentParams={noRowsOverlayComponentParams}
          />
        </div>
      </div>
    </AgGridProvider>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(
  <StrictMode>
    <GridExample />
  </StrictMode>,
);
```

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