---
title: "Provided Overlays"
framework: react
version: "36.1.0"
---

# Provided Overlays

The grid shows built-in overlays when data is loading or being exported and when there is no data or no rows match the current filter.

The following example demonstrates most of the provided overlays.

- Toggle the loading state to show/hide the loading overlay.
- Note that the loading overlay takes precedence over the other provided overlays if they are shown at the same time.
- Clear Row Data shows the no rows overlay.
- Set Non Matching Filter sets row data and a non-matching filter to show the no matching rows overlay.
- Export CSV exports the data to CSV and shows the exporting overlay.

#### Provided Overlays

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

import {
  ClientSideRowModelModule,
  CsvExportModule,
  TextFilterModule,
  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, TextFilterModule, CsvExportModule];

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

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

const defaultColDef: ColDef = {
  filter: true,
};

const rawRowData = [
  { athlete: "Michael Phelps", country: "US" },
  { athlete: "Chris Hoy", country: "UK" },
];

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

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

          <button onClick={() => setRowData(rawRowData)}>Set Row Data</button>
          <button onClick={() => setRowData([])}>Clear Row Data</button>
          <button
            onClick={() => {
              setRowData(rawRowData);
              gridRef.current?.api.setFilterModel({
                country: {
                  filterType: "text",
                  type: "equals",
                  filter: "Spain",
                },
              });
            }}
          >
            Set Non Matching Filter
          </button>
          <button onClick={() => gridRef.current?.api.setFilterModel(null)}>
            Clear Filter
          </button>
          <button onClick={() => gridRef.current?.api.exportDataAsCsv()}>
            Export CSV
          </button>
        </div>

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

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

[Live example: Provided Overlays](https://www.ag-grid.com/examples/overlays-provided/provided-overlays/reactFunctionalTs/)

## Loading

The loading overlay is displayed when the grid property `loading` is set to `true` and takes precedence over the other provided overlays.

| 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) |

## No Rows

When there are no rows the grid automatically displays the no-rows overlay.

## No Matching Rows

The no-matching-rows overlay is displayed when the grid has rows but none of the rows match the current filter criteria.

## Exporting

The exporting overlay is displayed when data is being exported from the grid to CSV or Excel.

## File Input

When `processFileInput` is provided and `rowData` is not set, the grid shows a built-in file input overlay. Users can drag a file onto the overlay or click the browse button to select one. The `processFileInput` callback receives a `params` object containing the selected `files` along with `success` and `fail` callbacks, enabling the application to parse the files and load or reject the data.

The file input overlay pairs well with [Auto-Generate Columns](https://www.ag-grid.com/react-data-grid/auto-generate-columns/#file-drop-overlay) to load data without defining columns upfront. See that page for the `processFileInput` callback and a worked example.

## Customisation

The provided overlays can be customised to change their content or completely replaced with custom components. The grid still manages the timing of when the overlays are displayed based on grid state.

### Text Customisation

Customise the text within the provided overlays via the `overlayComponentParams` grid option using the `OverlayComponentUserParams` interface.

Properties available on the `OverlayComponentUserParams` interface.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `loading` | `LoadingOverlayUserParams` |  |  | Parameters to customise the provided loading overlay. |
| `noRows` | `NoRowsOverlayUserParams` |  |  | Parameters to customise the provided no-rows overlay. |
| `noMatchingRows` | `NoMatchingRowsOverlayUserParams` |  |  | Parameters to customise the provided no-matching-rows overlay. |
| `exporting` | `ExportingOverlayUserParams` |  |  | Parameters to customise the provided exporting overlay. |
| `fileInput` | `FileInputOverlayUserParams` |  |  | Parameters to customise the provided file drop overlay. |

```jsx
const overlayComponentParams = {
    loading: { overlayText: 'Please wait while your data is loading...' },
    noRows: { overlayText: 'This grid has no data!' },
    noMatchingRows: { overlayText: 'Current Filter Matches No Rows' },
    exporting: { overlayText: 'Exporting your data...' },
    fileInput: { overlayText: 'Provide a file...' },
};

<AgGridReact overlayComponentParams={overlayComponentParams} />
```

#### Provided Overlays Custom Text

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

import {
  ClientSideRowModelModule,
  CsvExportModule,
  TextFilterModule,
  enableDevValidations,
} from "ag-grid-community";
import type { ColDef, OverlayComponentUserParams } 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, CsvExportModule, TextFilterModule];

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

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

const defaultColDef: ColDef = {
  filter: true,
};

const rawRowData = [
  { athlete: "Michael Phelps", country: "US" },
  { athlete: "Chris Hoy", country: "UK" },
];

const overlayComponentParams: OverlayComponentUserParams = {
  loading: { overlayText: "Please wait while your data is loading..." },
  noRows: { overlayText: "This grid has no data!" },
  noMatchingRows: { overlayText: "Current Filter Matches No Rows" },
  exporting: { overlayText: "Exporting your data..." },
};
const GridExample = () => {
  const [loading, setLoading] = useState(true);
  const [rowData, setRowData] = useState<IAthlete[] | undefined>();
  const gridRef = useRef<AgGridReact>(null);

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

          <button onClick={() => setRowData(rawRowData)}>Set Row Data</button>
          <button onClick={() => setRowData([])}>Clear Row Data</button>
          <button
            onClick={() => {
              setRowData(rawRowData);
              gridRef.current?.api.setFilterModel({
                country: {
                  filterType: "text",
                  type: "equals",
                  filter: "Spain",
                },
              });
            }}
          >
            Set Non Matching Filter
          </button>
          <button onClick={() => gridRef.current?.api.setFilterModel(null)}>
            Clear Filter
          </button>
          <button onClick={() => gridRef.current?.api.exportDataAsCsv()}>
            Export CSV
          </button>
        </div>

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

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

[Live example: Provided Overlays Custom Text](https://www.ag-grid.com/examples/overlays-provided/provided-overlays-text/reactFunctionalTs/)

### Custom Overlay Components

Then set the custom overlay to its matching key in the `components` map as described in [Overriding Grid Components](https://www.ag-grid.com/react-data-grid/components/#overriding-grid-components). Custom parameters can be supplied via the `overlayComponentParams` grid option.

```jsx
const components = {
    agLoadingOverlay: CustomLoadingOverlay,
    agNoRowsOverlay: CustomNoRowsOverlay,
    agNoMatchingRowsOverlay: CustomNoMatchingRows,
    agExportingOverlay: CustomExportingOverlay
};

<AgGridReact components={components} />
```

### Overlay Component Selector

To dynamically override a provided overlay with a custom component implement the `overlayComponentSelector(params)` callback. The callback params include an `overlayType` property which identifies which of the provided overlays that grid wants to display. The return type should match the `OverlaySelectorResult` interface.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `overlayComponentSelector` | `OverlaySelectorFunc` |  |  | Callback to dynamically provide a custom overlay component complete with custom params based on the selector params. [Initial](https://www.ag-grid.com/react-data-grid/grid-interface/#initial-grid-options). |

Returning `undefined` from the selector will fall back to the overlay specified in `params.overlayType`.

```jsx
const overlayComponentSelector = (params) => {
    if (params.overlayType === 'loading') {
        return {
            component: CustomLoadingOverlay,
            params: {
                loadingMessage: 'Please wait while data is loading...'
            }
        };
    }
    // return undefined to use the provided overlay for other overlay types
    return undefined;
};

<AgGridReact overlayComponentSelector={overlayComponentSelector} />
```

In the example below the loading overlay is overridden via the `overlayComponentSelector` but the no rows overlay is not.

#### Overlay Component Selector

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

import {
  ClientSideRowModelModule,
  enableDevValidations,
} from "ag-grid-community";
import type { ColDef, IOverlayParams } 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 = [ClientSideRowModelModule];

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

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

const rowData: IAthlete[] = [];

const defaultColDef: ColDef = {
  flex: 1,
};

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

  const overlayComponentSelector = useCallback((params: IOverlayParams) => {
    if (params.overlayType === "loading") {
      return {
        component: CustomLoadingOverlay,
        params: {
          loadingMessage: "Please wait while data is loading...",
        },
      };
    }
    // return undefined to use the provided overlay for other overlay types
    return 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>
        </div>

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

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

[Live example: Overlay Component Selector](https://www.ag-grid.com/examples/overlays-provided/custom-overlay-selector/reactFunctionalTs/)

### Combined Overlay Component

Provide a custom component to `overlayComponent` to be used in place of all the provided overlays. The custom component receives a `overlayType` parameter which identifies which of the provided overlays should be displayed. This can be used to conditionally render different content based on the overlay type.

Custom parameters can be supplied to the overlay component via the `overlayComponentParams` grid option.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `overlayComponent` | `any` |  |  | Provide a custom overlay component to be used for all grid provided overlays (loading, no rows, no matching rows, exporting etc). [Initial](https://www.ag-grid.com/react-data-grid/grid-interface/#initial-grid-options). |
| `overlayComponentParams` | `any` |  |  | Customise the parameters provided to the `overlayComponent`. Provided overlays accept parameters specified on the `OverlayComponentUserParams` interface. Any custom parameters can also be provided for custom overlay components. |

```jsx
const overlayComponent = CustomOverlay;
const overlayComponentParams = {
    loadingMessage: 'Custom loading message',
    noRowsMessage: 'Custom no rows message'
};

<AgGridReact
    overlayComponent={overlayComponent}
    overlayComponentParams={overlayComponentParams}
/>
```

In the example below a single custom component is provided to the grid which contains the conditional logic about what to render for each `overlayType`.

#### Overlay Component

```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 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" }, { field: "country" }];

const rowData: IAthlete[] = [];

const defaultColDef: ColDef = {
  flex: 1,
};

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

  const overlayComponentParams = useMemo(() => {
    return {
      loadingMessage: "Custom loading message",
      noRowsMessage: "Custom no rows message",
    };
  }, []);

  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}
            overlayComponent={CustomOverlay}
            overlayComponentParams={overlayComponentParams}
          />
        </div>
      </div>
    </AgGridProvider>
  );
};

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

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

## Suppress Overlays

Each provided overlay can be suppressed via the `suppressOverlays` grid option which accepts an array of overlay types to suppress.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `suppressOverlays` | `OverlayType[]` |  |  | List of provided overlay names to suppress. One of `loading`, `noRows`, `noMatchingRows`, `exporting`, `fileInput`. |

## Legacy Customisation

Previously, the loading and no-rows overlays were customised via: `loadingOverlayComponent` and `noRowsOverlayComponent`. This approach is now superseded by the `overlayComponent` but the properties remain for backwards compatibility. The documentation for these properties is available [here](https://www.ag-grid.com/react-data-grid/overlays/).