---
title: "Provided Overlays"
framework: vue
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 {
  createApp,
  defineComponent,
  onBeforeMount,
  ref,
  shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import "./styles.css";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  CsvExportModule,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  TextFilterModule,
  enableDevValidations,
} from "ag-grid-community";
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

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

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

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <div class="example-wrapper">
      <div>
        <label class="checkbox">
          <input type="checkbox" checked="" v-on:change="setLoading($event.currentTarget.checked)">
            loading
          </label>
          <button v-on:click="onBtnSetRowData()">Set Row Data</button>
          <button v-on:click="onBtnClearRowData()">Clear Row Data</button>
          <button v-on:click="onBtnSetFilter()">Set Non Matching Filter</button>
          <button v-on:click="onBtnClearFilter()">Clear Filter</button>
          <button v-on:click="onCsvExport()">Export CSV</button>
        </div>
        <ag-grid-vue
          style="width: 100%; height: 100%;"
          @grid-ready="onGridReady"
          :loading="true"
          :defaultColDef="defaultColDef"
          :columnDefs="columnDefs"
          :rowData="rowData"></ag-grid-vue>
        </div>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IAthlete> | null>(null);
    const defaultColDef = ref<ColDef>({
      filter: true,
    });
    const columnDefs = ref<ColDef[]>([
      { field: "athlete" },
      { field: "country" },
    ]);
    const rowData = ref<IAthlete[]>(null);

    function setLoading(value: boolean) {
      gridApi.value!.setGridOption("loading", value);
    }
    function onBtnClearRowData() {
      gridApi.value!.setGridOption("rowData", []);
    }
    function onBtnSetRowData() {
      gridApi.value!.setGridOption("rowData", [
        { athlete: "Michael Phelps", country: "US" },
        { athlete: "Chris Hoy", country: "UK" },
      ]);
    }
    function onBtnSetFilter() {
      gridApi.value!.setGridOption("rowData", [
        { athlete: "Michael Phelps", country: "US" },
        { athlete: "Chris Hoy", country: "UK" },
      ]);
      gridApi.value!.setFilterModel({
        country: { filterType: "text", type: "equals", filter: "Spain" },
      });
    }
    function onBtnClearFilter() {
      gridApi.value!.setFilterModel(null);
    }
    function onCsvExport() {
      gridApi.value!.exportDataAsCsv();
    }
    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;
    };

    return {
      gridApi,
      defaultColDef,
      columnDefs,
      rowData,
      onGridReady,
      setLoading,
      onBtnClearRowData,
      onBtnSetRowData,
      onBtnSetFilter,
      onBtnClearFilter,
      onCsvExport,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");
```

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

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

```ts
<ag-grid-vue
    :overlayComponentParams="overlayComponentParams"
    /* other grid options ... */>
</ag-grid-vue>

this.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...' },
};
```

#### Provided Overlays Custom Text

```ts
import {
  createApp,
  defineComponent,
  onBeforeMount,
  ref,
  shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import "./styles.css";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  CsvExportModule,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  OverlayComponentUserParams,
  TextFilterModule,
  enableDevValidations,
} from "ag-grid-community";
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

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

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

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <div class="example-wrapper">
      <div>
        <label class="checkbox">
          <input type="checkbox" checked="" v-on:change="setLoading($event.currentTarget.checked)">
            loading
          </label>
          <button v-on:click="onBtnSetRowData()">Set Row Data</button>
          <button v-on:click="onBtnClearRowData()">Clear Row Data</button>
          <button v-on:click="onBtnSetFilter()">Set Non Matching Filter</button>
          <button v-on:click="onBtnClearFilter()">Clear Filter</button>
          <button v-on:click="onCsvExport()">Export CSV</button>
        </div>
        <ag-grid-vue
          style="width: 100%; height: 100%;"
          @grid-ready="onGridReady"
          :overlayComponentParams="overlayComponentParams"
          :loading="true"
          :defaultColDef="defaultColDef"
          :columnDefs="columnDefs"
          :rowData="rowData"></ag-grid-vue>
        </div>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IAthlete> | null>(null);
    const overlayComponentParams = ref({
      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 defaultColDef = ref<ColDef>({
      filter: true,
    });
    const columnDefs = ref<ColDef[]>([
      { field: "athlete" },
      { field: "country" },
    ]);
    const rowData = ref<IAthlete[]>(null);

    function setLoading(value: boolean) {
      gridApi.value!.setGridOption("loading", value);
    }
    function onBtnClearRowData() {
      gridApi.value!.setGridOption("rowData", []);
    }
    function onBtnSetRowData() {
      gridApi.value!.setGridOption("rowData", [
        { athlete: "Michael Phelps", country: "US" },
        { athlete: "Chris Hoy", country: "UK" },
      ]);
    }
    function onBtnSetFilter() {
      gridApi.value!.setGridOption("rowData", [
        { athlete: "Michael Phelps", country: "US" },
        { athlete: "Chris Hoy", country: "UK" },
      ]);
      gridApi.value!.setFilterModel({
        country: { filterType: "text", type: "equals", filter: "Spain" },
      });
    }
    function onBtnClearFilter() {
      gridApi.value!.setFilterModel(null);
    }
    function onCsvExport() {
      gridApi.value!.exportDataAsCsv();
    }
    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;
    };

    return {
      gridApi,
      overlayComponentParams,
      defaultColDef,
      columnDefs,
      rowData,
      onGridReady,
      setLoading,
      onBtnClearRowData,
      onBtnSetRowData,
      onBtnSetFilter,
      onBtnClearFilter,
      onCsvExport,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");
```

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

### Custom Overlay Components

Any valid Vue component can be an overlay component, however it is also possible to implement the following optional methods:

```ts

interface ILoadingOverlay&lt;TData = any, TContext = any&gt; {
  // Gets called when the `overlayComponentParams` grid option is updated
  refresh?(params: TParams): void;

}
```

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

```ts
<ag-grid-vue
    :components="components"
    /* other grid options ... */>
</ag-grid-vue>

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

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

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

```ts
<ag-grid-vue
    :overlayComponentSelector="overlayComponentSelector"
    /* other grid options ... */>
</ag-grid-vue>

this.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;
};
```

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

#### Overlay Component Selector

```ts
import {
  createApp,
  defineComponent,
  onBeforeMount,
  ref,
  shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import "./styles.css";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  GridApi,
  GridOptions,
  GridReadyEvent,
  IOverlayParams,
  ModuleRegistry,
  OverlaySelectorFunc,
  enableDevValidations,
} from "ag-grid-community";
import CustomLoadingOverlay from "./customLoadingOverlayVue";
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([ClientSideRowModelModule]);

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

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <div class="example-wrapper">
      <div>
        <label class="checkbox">
          <input type="checkbox" checked="" v-on:change="setLoading($event.currentTarget.checked)">
            loading
          </label>
        </div>
        <ag-grid-vue
          style="width: 100%; height: 100%;"
          @grid-ready="onGridReady"
          :columnDefs="columnDefs"
          :rowData="rowData"
          :defaultColDef="defaultColDef"
          :loading="true"
          :overlayComponentSelector="overlayComponentSelector"></ag-grid-vue>
        </div>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
    CustomLoadingOverlay,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IAthlete> | null>(null);
    const columnDefs = ref<ColDef[]>([
      { field: "athlete" },
      { field: "country" },
    ]);
    const rowData = ref<IAthlete[] | null>([]);
    const defaultColDef = ref<ColDef>({
      flex: 1,
    });
    const overlayComponentSelector = ref<OverlaySelectorFunc>(
      (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.value!.setGridOption("loading", value);
    }
    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;
    };

    return {
      gridApi,
      columnDefs,
      rowData,
      defaultColDef,
      overlayComponentSelector,
      onGridReady,
      setLoading,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");
```

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

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

```ts
<ag-grid-vue
    :overlayComponent="overlayComponent"
    :overlayComponentParams="overlayComponentParams"
    /* other grid options ... */>
</ag-grid-vue>

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

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 {
  createApp,
  defineComponent,
  onBeforeMount,
  ref,
  shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import "./styles.css";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  enableDevValidations,
} from "ag-grid-community";
import CustomOverlay from "./customOverlayVue";
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([ClientSideRowModelModule]);

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

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <div class="example-wrapper">
      <div>
        <label class="checkbox">
          <input type="checkbox" checked="" v-on:change="setLoading($event.currentTarget.checked)">
            loading
          </label>
        </div>
        <ag-grid-vue
          style="width: 100%; height: 100%;"
          @grid-ready="onGridReady"
          :columnDefs="columnDefs"
          :defaultColDef="defaultColDef"
          :loading="true"
          :rowData="rowData"
          :overlayComponent="overlayComponent"
          :overlayComponentParams="overlayComponentParams"></ag-grid-vue>
        </div>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
    CustomOverlay,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IAthlete> | null>(null);
    const columnDefs = ref<ColDef[]>([
      { field: "athlete" },
      { field: "country" },
    ]);
    const defaultColDef = ref<ColDef>({
      flex: 1,
    });
    const rowData = ref<IAthlete[] | null>([]);
    const overlayComponent = ref("CustomOverlay");
    const overlayComponentParams = ref({
      loadingMessage: "Custom loading message",
      noRowsMessage: "Custom no rows message",
    });

    function setLoading(value: boolean) {
      gridApi.value!.setGridOption("loading", value);
    }
    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;
    };

    return {
      gridApi,
      columnDefs,
      defaultColDef,
      rowData,
      overlayComponent,
      overlayComponentParams,
      onGridReady,
      setLoading,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");
```

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

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