JavaScript Data Grid Tooltip Component
Tooltip components allow you to add your own tooltips to the grid's column headers and cells. Use these when the provided tooltip component or the default browser tooltip do not meet your requirements.
Simple Tooltip Component
Below is an example of a tooltip component:
class CustomTooltip {
init(params) {
const eGui = this.eGui = document.createElement('div');
const color = params.color || 'white';
const data = params.api.getDisplayedRowAtIndex(params.rowIndex).data;
eGui.classList.add('custom-tooltip');
eGui.style['background-color'] = color;
eGui.innerHTML = `
<span class"name">${data.athlete}</span>
<span>Country: </span>
${data.country}
<span>Total: </span>
${data.total}
getGui() {
return this.eGui;
Example: Custom Tooltip
The example below demonstrates how to provide custom tooltips to the grid. Notice the following:
- The Custom Tooltip Component is supplied by name via
colDef.tooltipComponent.
- The Custom Tooltip Parameters (for tooltip background color) are supplied using
colDef.tooltipComponentParams.
- Tooltips are displayed instantly by setting
tooltipShowDelay to 0.
- Tooltips hide in 2000ms by setting
tooltipHideDelay to 2000.
- Tooltips will be shown for the
athlete and country columns
Tooltip Component Interface
Implement this interface to provide a custom tooltip.
interface ITooltipComp {
// The init(params) method is called on the tooltip component once. See below for details on the parameters.
init(params: ITooltipParams): void;
// Returns the DOM element for this tooltip
getGui(): HTMLElement;
The interface for the init parameters is as follows:
Properties available on the ITooltipParams<TData = any, TValue = any, TContext = any> interface.
location
TypeTooltipLocation What part of the application is showing the tooltip, e.g. 'cell', 'header', 'menuItem' etc value
TypeTValue | null The value to be rendered by the tooltip. value Formatted
Typestring | null The formatted value to be rendered by the tooltip. col Def
TypeColDef | ColGroupDef | null Column / ColumnGroup definition. column
Column / ColumnGroup row Index
Type
number The index of the row containing the cell rendering the tooltip. node
TypeIRowNode The row node. data
TypeTData Data for the row node in question. hide Tooltip Callback
TypeFunction A callback function that hides the tooltip api
TypeGridApi The grid api. column Api
TypeColumnApi The column api. context
TypeTContext Application context as set on gridOptions.context.
Registering Custom Tooltip Components
See the registering custom components section for details on registering and using custom tooltip components.
Default Browser Tooltip
If you don't want to use the grid's tooltip component, you can use the enableBrowserTooltips config to use the browser's default tooltip. The grid will simply set an element's title attribute to display the tooltip.
Tooltip Show and Hide Delay
By default, when you hover on an item, it will take 2 seconds for the tooltip to be displayed and then 10 seconds for the tooltip to hide. If you need to change these delays, the tooltipShowDelay and tooltipHideDelay configs should be used, which are set in milliseconds.
The delays will have no effect if you are using browser tooltips, as they are controlled entirely by the browser.
Showing Blank Values
The grid will not show a tooltip if there is no value to show. This is the default behaviour as the simplest form of tooltip will show the value it is provided without any additional information. In this case, it would be strange to show the tooltip with no value as that would show as a blank box.
This can be a problem if you wish a tooltip to display for blank values. For example, you might want to display a tooltip saying "This cell has no value" instead. To achieve this, you should utilise tooltipValueGetter to return something different when the value is blank.
The example below shows both displaying and not displaying the tooltip for blank values. Note the following:
- The first three rows have athlete values of
undefined, null and '' (empty string).
- The column Athlete Col 1 uses
tooltipField for the tooltip field. When there is no value (the first three rows) no tooltip is displayed.
- The column Athlete Col 2 uses
tooltipValueGetter for the tooltip field. The value getter will return a value (an object) regardless of whether the value to display is empty or not. This ensures the tooltip gets displayed even when no cell value is present.
Header Tooltip with Custom Tooltip
When we want to display a header tooltip, we set the headerTooltip config as a string, and that string will be displayed as the tooltip. However, when working with custom tooltips we set colDef.tooltipComponent to assign the column's tooltip component and the headerTooltip value will passed to the params object.
If headerTooltip is not present, the tooltip will not be rendered.
The example below shows how to set a custom tooltip to a header and to a grouped header. Note the following:
- The column Athlete Col 1 does not have a
tooltipComponent so it will render the value set in its headerTooltip config.
- The column Athlete Col 2 uses
tooltipComponent so the the value in headerTooltip is passed to the tooltipComponent params to be used.
- The
tooltipComponent detects that it's being rendered by a header because the params object does not contain a rowIndex value.
Example: Tooltips With Row Groups
The example below shows how to use the default tooltip component with group columns. Because the group column has no real field assigned to it, the tooltipValueGetter function must be used.
Mouse Tracking
The example below enables mouse tracking to demonstrate a scenario where tooltips need to follow the cursor. To enable this feature, set the tooltipMouseTrack to true in the gridOptions.
Interactive Tooltips
By default, it is impossible to click on tooltips and hovering them has no effect. If tooltipInteraction=true is set in the gridOptions, the tooltips will not disappear while being hovered and you will be able to click and select the text within the tooltip.
const gridOptions = {
tooltipInteraction: true,
// other grid options ...
}
The example below enables tooltip interaction to demonstrate a scenario where tooltips will not disappear while hovered. Note following:
- Tooltip is enabled for the Athlete and Country columns.
- Tooltips will not disappear while being hovered.
- Tooltips content can be selected and copied.