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

```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";
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>
          <button v-on:click="onBtnClearRowData()">Clear rowData</button>
          <button v-on:click="onBtnSetRowData()">Set rowData</button>
        </div>
        <ag-grid-vue
          style="width: 100%; height: 100%;"
          @grid-ready="onGridReady"
          :loading="true"
          :columnDefs="columnDefs"
          :rowData="rowData"></ag-grid-vue>
        </div>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IAthlete> | null>(null);
    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" },
      ]);
    }
    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;
    };

    return {
      gridApi,
      columnDefs,
      rowData,
      onGridReady,
      setLoading,
      onBtnClearRowData,
      onBtnSetRowData,
    };
  },
});

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

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

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

```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";
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>
        <button v-on:click="onBtnClearRowData()">Clear rowData</button>
        <button v-on:click="onBtnSetRowData()">Set rowData</button>
      </div>
      <ag-grid-vue
        style="width: 100%; height: 100%;"
        @grid-ready="onGridReady"
        :rowData="rowData"
        :columnDefs="columnDefs"></ag-grid-vue>
      </div>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IAthlete> | null>(null);
    const rowData = ref<IAthlete[] | null>([]);
    const columnDefs = ref<ColDef[]>([
      { field: "athlete" },
      { field: "country" },
    ]);

    function onBtnClearRowData() {
      gridApi.value!.setGridOption("rowData", []);
    }
    function onBtnSetRowData() {
      gridApi.value!.setGridOption("rowData", [
        { athlete: "Michael Phelps", country: "US" },
      ]);
    }
    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;
    };

    return {
      gridApi,
      rowData,
      columnDefs,
      onGridReady,
      onBtnClearRowData,
      onBtnSetRowData,
    };
  },
});

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

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

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

Any valid Vue component can be a loading 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;

}
```

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

#### Custom Loading Overlay Components

```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,
  TextEditorModule,
  TextFilterModule,
  enableDevValidations,
} from "ag-grid-community";
import CustomLoadingOverlay from "./customLoadingOverlayVue";
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  TextEditorModule,
  TextFilterModule,
  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"
          :loadingOverlayComponent="loadingOverlayComponent"
          :loadingOverlayComponentParams="loadingOverlayComponentParams"></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", width: 150 },
      { field: "country", width: 120 },
    ]);
    const rowData = ref<IAthlete[] | null>([
      { athlete: "Michael Phelps", country: "United States" },
      { athlete: "Natalie Coughlin", country: "United States" },
      { athlete: "Aleksey Nemov", country: "Russia" },
      { athlete: "Alicia Coutts", country: "Australia" },
    ]);
    const defaultColDef = ref<ColDef>({
      editable: true,
      flex: 1,
      minWidth: 100,
      filter: true,
    });
    const loadingOverlayComponent = ref("CustomLoadingOverlay");
    const loadingOverlayComponentParams = ref({
      loadingMessage: "One moment please...",
    });

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

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

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

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

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

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

```ts

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

}
```

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

#### Custom No Rows Overlay Components

```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,
  TextEditorModule,
  TextFilterModule,
  enableDevValidations,
} from "ag-grid-community";
import CustomNoRowsOverlay from "./customNoRowsOverlayVue";
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

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

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

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <div class="example-wrapper">
      <div>
        <button v-on:click="onBtnClearRowData()">Clear rowData</button>
        <button v-on:click="onBtnSetRowData()">Set rowData</button>
      </div>
      <ag-grid-vue
        style="width: 100%; height: 100%;"
        @grid-ready="onGridReady"
        :columnDefs="columnDefs"
        :defaultColDef="defaultColDef"
        :rowData="rowData"
        :noRowsOverlayComponent="noRowsOverlayComponent"
        :noRowsOverlayComponentParams="noRowsOverlayComponentParams"></ag-grid-vue>
      </div>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
    CustomNoRowsOverlay,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IAthlete> | null>(null);
    const columnDefs = ref<ColDef[]>([
      { field: "athlete", width: 150 },
      { field: "country", width: 120 },
    ]);
    const defaultColDef = ref<ColDef>({
      editable: true,
      flex: 1,
      minWidth: 100,
      filter: true,
    });
    const rowData = ref<IAthlete[] | null>([]);
    const noRowsOverlayComponent = ref("CustomNoRowsOverlay");
    const noRowsOverlayComponentParams = ref({
      noRowsMessageFunc: () =>
        "No rows found at: " + new Date().toLocaleTimeString(),
    });

    function onBtnClearRowData() {
      gridApi.value!.setGridOption("rowData", []);
    }
    function onBtnSetRowData() {
      gridApi.value!.setGridOption("rowData", [
        { athlete: "Michael Phelps", country: "US" },
      ]);
    }
    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;
    };

    return {
      gridApi,
      columnDefs,
      defaultColDef,
      rowData,
      noRowsOverlayComponent,
      noRowsOverlayComponentParams,
      onGridReady,
      onBtnClearRowData,
      onBtnSetRowData,
    };
  },
});

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

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