JavaScript Data GridProvided Overlays

The grid shows overlays to communicate the grid's current state to the user. When data is loading or being exported and when there is no data or no rows match the current filter.

Loading Copy Link

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

No Rows Copy Link

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

No Matching Rows Copy Link

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

Exporting Copy Link

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

Example Copy Link

The following example demonstrates all 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 the row data to show the no rows overlay.
• Set Non Matching Filter, sets row data and a non matching filter to show the no matching rows overlay.
• Export the data to CSV

Customisation Copy Link

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 Copy Link

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

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

    // other grid options ...
}

Custom Overlay Components Copy Link

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.

interface ILoadingOverlayComp<TData = any, TContext = any> {
  // 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 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. Custom parameters can be supplied via the overlayComponentParams grid option.

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

    // other grid options ...
}

Overlay Component Selector Copy Link

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.

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

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.

Combined Overlay Component Copy Link

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.

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.

Suppress Overlays Copy Link

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

Legacy Customisation Copy Link

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.