JavaScript Data GridActive Overlay

Version 36.2.0

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.

main.ts

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

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

ModuleRegistry.registerModules([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" },
];

let gridApi: GridApi<IAthlete>;

const activeOverlayParams: CustomParams = {
  count: 1,
};

const gridOptions: GridOptions<IAthlete> = {
  columnDefs,
  rowData,
  activeOverlay: CustomOverlay,
  activeOverlayParams,
};

function showActiveOverlay() {
  gridApi.setGridOption("activeOverlay", CustomOverlay);
}

function clearActiveOverlay() {
  gridApi.setGridOption("activeOverlay", undefined);
}
function incParam() {
  activeOverlayParams.count++;
  gridApi.setGridOption("activeOverlayParams", activeOverlayParams);
}

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).showActiveOverlay = showActiveOverlay;
  (<any>window).clearActiveOverlay = clearActiveOverlay;
  (<any>window).incParam = incParam;
}

styles.css

.example-wrapper {
    display: flex;
    flex-direction: column;
    height: 100%;
}

.button-row {
    display: flex;
    flex-wrap: wrap;
    gap: 12px;
    padding: 12px;
}

.button-row button {
    padding: 4px 12px;
}

.grid-wrapper {
    flex: 1 1 0;
    min-height: 0;
}

.my-custom-overlay {
    padding: 16px;
    font-size: 32px;
    background: rgba(0, 0, 0, 0.1);
    border-radius: 20px;
}

customOverlay.ts

import type { IOverlayComp, IOverlayParams } from 'ag-grid-community';

export interface CustomParams {
    count: number;
}

export class CustomOverlay implements IOverlayComp {
    private eGui!: HTMLElement;

    public init(params: IOverlayParams & CustomParams): void {
        const eGui = document.createElement('div');
        this.eGui = eGui;
        eGui.className = 'my-custom-overlay';
        this.refresh(params);
    }

    public getGui(): HTMLElement {
        return this.eGui;
    }

    public refresh(params: IOverlayParams & CustomParams) {
        this.eGui.textContent = 'Custom Overlay: ' + params.count;
    }
}

index.html

<div class="example-wrapper">
    <div class="button-row">
        <button onclick="showActiveOverlay()">Show custom overlay</button>
        <button onclick="clearActiveOverlay()">Hide custom overlay</button>
        <button onclick="incParam()">Increment Param</button>
    </div>
    <div class="grid-wrapper" id="myGrid"></div>
</div>

Display an Active Overlay Copy Link

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

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.

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.

Implement the IOverlayComp interface to provide a custom overlay the grid will supply IOverlayParams whenever the component is created or refreshed.


interface IOverlayComp<TData = any, TContext = any, TParams extends Readonly<IOverlayParams<TData, TContext>> = IOverlayParams<TData, TContext>> {
  // Return the DOM element of your component, this is what the grid puts into the DOM 
  getGui(): HTMLElement;

  // 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<void>  |  void;

  // Gets called when the `overlayComponentParams` grid option is updated
  refresh?(params: TParams): void;

}

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 map and shown by setting activateOverlay = "statusOverlay" to the key used.

main.ts

import {
  ClientSideRowModelModule,
  ColDef,
  GridApi,
  GridOptions,
  ModuleRegistry,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { StatusOverlay } from "./statusOverlay";

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

ModuleRegistry.registerModules([ClientSideRowModelModule]);

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

const columnDefs: ColDef<IAthlete>[] = [
  { field: "athlete", flex: 1 },
  { field: "country", flex: 1 },
];

const rowData: IAthlete[] = [
  { athlete: "Michael Phelps", country: "United States" },
  { athlete: "Alicia Coutts", country: "Australia" },
];

let gridApi: GridApi<IAthlete>;
let statusOverlayCounter = 0;

const gridOptions: GridOptions<IAthlete> = {
  columnDefs,
  rowData,
  components: {
    statusOverlay: StatusOverlay,
  },
};

function showNoRowsOverlay() {
  gridApi.updateGridOptions({
    activeOverlay: "agNoRowsOverlay",
    activeOverlayParams: undefined,
  });
}

function showStatusOverlay() {
  gridApi.updateGridOptions({
    activeOverlay: "statusOverlay",
    activeOverlayParams: {
      myCounter: ++statusOverlayCounter,
    },
  });
}

function hideOverlay() {
  gridApi.updateGridOptions({
    activeOverlay: undefined,
    activeOverlayParams: undefined,
  });
}

function setLoading(isChecked: boolean) {
  gridApi.updateGridOptions({
    loading: isChecked ? true : undefined,
  });
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

const loadingToggle =
  document.querySelector<HTMLInputElement>("#loading-toggle");
if (loadingToggle) {
  loadingToggle.addEventListener("change", () =>
    setLoading(loadingToggle.checked),
  );
  setLoading(loadingToggle.checked);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).showNoRowsOverlay = showNoRowsOverlay;
  (<any>window).showStatusOverlay = showStatusOverlay;
  (<any>window).hideOverlay = hideOverlay;
}

styles.css

.example-wrapper {
    display: flex;
    flex-direction: column;
    height: 100%;
}

.button-row {
    display: flex;
    flex-wrap: wrap;
    gap: 12px;
    padding: 12px;
}

.button-row button {
    padding: 4px 12px;
}

.button-row .loading-toggle {
    display: inline-flex;
    align-items: center;
    gap: 6px;
    font-weight: 600;
    user-select: none;
}

.grid-wrapper {
    flex: 1 1 0;
    min-height: 0;
}

.status-overlay {
    padding: 16px;
    border-radius: 16px;
    border: 3px solid pink;
    font-size: 32px;
}

statusOverlay.ts

import type { IOverlayComp, IOverlayParams } from 'ag-grid-community';

export interface StatusOverlayParams extends IOverlayParams {
    myCounter?: number;
}

export class StatusOverlay implements IOverlayComp {
    private eGui: HTMLDivElement;
    private eBody: HTMLDivElement;

    public constructor() {
        this.eGui = document.createElement('div');
        this.eBody = document.createElement('div');
    }

    public init(params: StatusOverlayParams): void {
        const { eGui, eBody } = this;

        eGui.className = 'status-overlay';
        eGui.append(eBody);

        this.refresh(params);
    }

    public getGui(): HTMLElement {
        return this.eGui;
    }

    public refresh(params: StatusOverlayParams): void {
        this.eBody.innerText = `custom: ${params.myCounter}`;
    }

    public destroy(): void {
        // no-op
    }
}

index.html

<div class="example-wrapper">
    <div class="button-row">
        <label class="toggle loading-toggle"> <input id="loading-toggle" type="checkbox" /> Loading </label>
        <button onclick="showNoRowsOverlay()">activeOverlay = agNoRowsOverlay</button>
        <button onclick="showStatusOverlay()">activeOverlay = CustomOverlay</button>
        <button onclick="hideOverlay()">Hide activeOverlay</button>
    </div>
    <div class="grid-wrapper" id="myGrid"></div>
</div>

Getting Started

AI Features

Layout & Styling

Charting

Core Features

Advanced Features

JavaScript Data GridActive Overlay

Display an Active Overlay Copy Link