---
title: "Active Overlay"
framework: react
version: "36.1.0"
---

# Active Overlay

Applications can display an overlay on demand regardless of grid state. This is achieved by providing an active overlay which can be one of the provided overlays or be a custom overlay component.

#### Active Overlay (Component Class)

```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 type { CustomParams } from "./customOverlay";
import { CustomOverlay } from "./customOverlay";
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", flex: 1 },
  { field: "country", flex: 1 },
];

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 GridExample = () => {
  const [activeOverlay, setActiveOverlay] = useState<any>(() => CustomOverlay);
  const [activeOverlayParams, setActiveOverlayParams] = useState<CustomParams>({
    count: 1,
  });

  return (
    <AgGridProvider modules={modules}>
      <div className="example-wrapper">
        <div className="button-row">
          <button onClick={() => setActiveOverlay(() => CustomOverlay)}>
            Show custom overlay
          </button>
          <button onClick={() => setActiveOverlay(undefined)}>
            Hide custom overlay
          </button>
          <button
            onClick={() =>
              setActiveOverlayParams((prev) => ({ count: prev.count + 1 }))
            }
          >
            Increment Param
          </button>
        </div>

        <div className="grid-wrapper">
          <AgGridReact<IAthlete>
            rowData={rowData}
            columnDefs={columnDefs}
            activeOverlay={activeOverlay}
            activeOverlayParams={activeOverlayParams}
          />
        </div>
      </div>
    </AgGridProvider>
  );
};

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

[Live example: Active Overlay (Component Class)](https://www.ag-grid.com/examples/overlays-active/active-overlay-component/reactFunctionalTs/)

## Display an Active Overlay

To display an overlay on demand set the `activeOverlay` / `activeOverlayParams` grid option. To clear the overlay set `activeOverlay = undefined`.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `activeOverlay` | `any` |  |  | Display an overlay on demand. If provided takes precedence over the grid provided overlays. - name of a provided overlay, i.e `agLoadingOverlay`, `agNoRowsOverlay`, `agNoMatchingRowsOverlay`, `agExportingOverlay` - component class/function. - key of a custom component registered in the `components` map. - `undefined` to clear. |
| `activeOverlayParams` | `any` |  |  | Custom parameters to be supplied to the `activeOverlay` component in addition to `IOverlayParams`. Updating the params will trigger a refresh of the active overlay. |

The example below demonstrates using the grid provided overlays as an active overlay. Note the following:

- activeOverlays take precedence over the provided loading overlay.
- activeOverlay can be displayed no matter what the grid state, i.e showing the no-rows overlay even when there are rows.
- StatusOverlay is registered in the [components](https://www.ag-grid.com/react-data-grid/components/#2-by-name) map and shown by setting `activateOverlay = "statusOverlay"` to the key used.

#### Active Overlay Switcher

```tsx
'use client';
import React, { StrictMode, useMemo, 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 StatusOverlay from "./statusOverlay";
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", flex: 1 },
  { field: "country", flex: 1 },
];

const rowData: IAthlete[] = [
  { athlete: "Michael Phelps", country: "United States" },
  { athlete: "Natalie Coughlin", country: "United States" },
];

const GridExample = () => {
  const components = useMemo(() => ({ statusOverlay: StatusOverlay }), []);
  const [activeOverlay, setActiveOverlay] = useState<string | undefined>();
  const [loading, setLoading] = useState<boolean | undefined>(undefined);

  const setNoRowsOverlay = () => {
    setActiveOverlay("agNoRowsOverlay");
  };

  const setCustomOverlay = () => {
    setActiveOverlay("statusOverlay");
  };

  const clearOverlay = () => {
    setActiveOverlay(undefined);
  };

  const onLoadingToggle = (event: React.ChangeEvent<HTMLInputElement>) => {
    setLoading(event.target.checked ? true : undefined);
  };

  return (
    <AgGridProvider modules={modules}>
      <div className="example-wrapper">
        <div className="button-row">
          <label className="toggle loading-toggle">
            <input
              type="checkbox"
              checked={loading === true}
              onChange={onLoadingToggle}
            />{" "}
            Loading
          </label>
          <button onClick={setNoRowsOverlay}>
            activeOverlay = agNoRowsOverlay
          </button>
          <button onClick={setCustomOverlay}>
            activeOverlay = CustomOverlay
          </button>
          <button onClick={clearOverlay}>Hide activeOverlay</button>
        </div>

        <div className="grid-wrapper">
          <AgGridReact
            rowData={rowData}
            columnDefs={columnDefs}
            components={components}
            loading={loading}
            activeOverlay={activeOverlay}
          />
        </div>
      </div>
    </AgGridProvider>
  );
};

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

[Live example: Active Overlay Switcher](https://www.ag-grid.com/examples/overlays-active/active-overlay-switcher/reactFunctionalTs/)