---
title: "Provided Overlays"
framework: javascript
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

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

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

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

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

let gridApi: GridApi<IAthlete>;

const gridOptions: GridOptions<IAthlete> = {
  loading: true,
  defaultColDef: {
    filter: 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" },
    { athlete: "Chris Hoy", country: "UK" },
  ]);
}

function onBtnSetFilter() {
  gridApi!.setGridOption("rowData", [
    { athlete: "Michael Phelps", country: "US" },
    { athlete: "Chris Hoy", country: "UK" },
  ]);
  gridApi!.setFilterModel({
    country: { filterType: "text", type: "equals", filter: "Spain" },
  });
}

function onBtnClearFilter() {
  gridApi!.setFilterModel(null);
}

function onCsvExport() {
  gridApi!.exportDataAsCsv();
}

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;
  (<any>window).onBtnSetFilter = onBtnSetFilter;
  (<any>window).onBtnClearFilter = onBtnClearFilter;
  (<any>window).onCsvExport = onCsvExport;
}
```

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

## 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/javascript-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. |

```js
const gridOptions = {
    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...' },
    },

    // other grid options ...
}
```

#### Provided Overlays Custom Text

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

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

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

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

let gridApi: GridApi<IAthlete>;

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 gridOptions: GridOptions<IAthlete> = {
  loading: true,
  defaultColDef: {
    filter: true,
  },
  columnDefs: [{ field: "athlete" }, { field: "country" }],
  overlayComponentParams,
};

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

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

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

function onBtnSetFilter() {
  gridApi!.setGridOption("rowData", [
    { athlete: "Michael Phelps", country: "US" },
    { athlete: "Chris Hoy", country: "UK" },
  ]);
  gridApi!.setFilterModel({
    country: { filterType: "text", type: "equals", filter: "Spain" },
  });
}

function onBtnClearFilter() {
  gridApi!.setFilterModel(null);
}

function onCsvExport() {
  gridApi!.exportDataAsCsv();
}

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;
  (<any>window).onBtnSetFilter = onBtnSetFilter;
  (<any>window).onBtnClearFilter = onBtnClearFilter;
  (<any>window).onCsvExport = onCsvExport;
}
```

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

### Custom Overlay Components

To provide a custom component for the provided overlays implement one of the following interfaces: `ILoadingOverlayComp`, `INoRowsOverlayComp`, `INoMatchingRowsOverlayComp` or `IExportingOverlayComp`.

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;

}
```

The `INoRowsOverlayComp`, `INoMatchingRowsOverlayComp` or `IExportingOverlayComp` interfaces follow a similar pattern to the `ILoadingOverlayComp` above.

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

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

    // other grid options ...
}
```

### 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/javascript-data-grid/grid-interface/#initial-grid-options). |

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

```js
const gridOptions = {
    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;
    },

    // other grid options ...
}
```

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

#### Overlay Component Selector

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  GridApi,
  GridOptions,
  IOverlayParams,
  ModuleRegistry,
  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([ClientSideRowModelModule]);

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

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

const rowData: IAthlete[] = [];

let gridApi: GridApi<IAthlete>;

const gridOptions: GridOptions<IAthlete> = {
  defaultColDef: {
    flex: 1,
  },

  loading: true,

  columnDefs: columnDefs,
  rowData,

  overlayComponentSelector: (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;
  },
};

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: Overlay Component Selector](https://www.ag-grid.com/examples/overlays-provided/custom-overlay-selector/typescript/)

### 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/javascript-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. |

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

    // other grid options ...
}
```

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

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  GridApi,
  GridOptions,
  ModuleRegistry,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { CustomOverlay } from "./customOverlay";

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

ModuleRegistry.registerModules([ClientSideRowModelModule]);

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

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

let gridApi: GridApi<IAthlete>;

const gridOptions: GridOptions<IAthlete> = {
  defaultColDef: {
    flex: 1,
  },

  loading: true,

  columnDefs: columnDefs,
  rowData: [],

  overlayComponent: CustomOverlay,
  overlayComponentParams: {
    loadingMessage: "Custom loading message",
    noRowsMessage: "Custom no rows message",
  },
};

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: Overlay Component](https://www.ag-grid.com/examples/overlays-provided/custom-overlay-component/typescript/)

## 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/javascript-data-grid/overlays/).