Column Tooltips

Add tooltips to column headers as either simple text tooltips or custom, tag-based markup with optional trigger icons.

You can choose from the default column-header style or match with the grid's internal-tooltip styling (text-tooltips only).

Simple Text Tooltip

To create a simple text tooltip, add header-tooltip-text to the desired column, like so:

<zg-column header-tooltip-text="I'm a tooltip"></zg-column>
<zg-column header-tooltip-text="I'm a tooltip <strong>with markup</strong>"></zg-column>

Header with Tooltips Grid

Here is a complete grid with tooltips in the header:

Top

Content From Renderer Function

Control the tooltip output by using a detached, renderer function. Adding complex or involved tooltip content via inline-attribute can get unwieldy, fast. For example, you might want each tooltip to have the same custom markup, but have dynamic text based on the column's type/data. Replicating the code inline for each column is fragile, inefficient, and not feasible for adding dynamic parts.

Instead, create a function (that returns a string) and associate it with the column, like so:

<zing-grid>
  <zg-colgroup>
    <zg-column header-tooltip-renderer="myTooltip"></zg-column>
  </zg-colgroup>
</zing-grid>
...
<script>
function myTooltip(data) {
  return `I'm a tooltip: <strong>${data.someValue}</strong>`;
}
</script>

header-tooltip-renderer looks for a function on the global scope.

.registerMethod()

If you can't access the function in your project in this fashion, use ZingGrid's method-registration system to tell the grid how to find it:

<zing-grid id="myGrid">
  <zg-colgroup>
    <zg-column ... header-tooltip-renderer="myTooltip"></zg-column>
  </zg-colgroup>
</zing-grid>
...
<script>
  const ZG = document.querySelector('#myGrid');
  ZG.registerMethod('myTooltip', yourFnReference);
</script>

The data provided to the function includes: the FOO (data.foo), the BAR (data.bar), and the BAZ (data.baz).

Top

Content From HTML Template

Control the tooltip output by using an HTML template (see below). Like the renderer function, you have access to dynamic data provided by the column.

<zing-grid>
  <zg-colgroup>
    <zg-column ... header-tooltip-template="myTooltip"></zg-column>
  </zg-colgroup>
</zing-grid>
...
<template id="myTooltip">
  I'm a tooltip: <strong>[[data.someValue]]</strong>
</template>

The data provided to the template includes: the FOO (data.foo), the BAR (data.bar), and the BAZ (data.baz).

Top

Tooltip Type and Styling

Column tooltips have their own distinct styling and composition that differs from the grid's internal 'system' tooltips (you can see these internal tooltips when hovering over the "Insert New Record" button or some "Caption" and "Pager" icons).

They also allow you to customize the structure and layout of the tooltip content by adding markup tags and dynamic content. Internal tooltips are plain-text and applied via CSS :before and :after selectors.

If you need the column tooltips to look like the internal tooltips for consistency, set header-tooltip-type="system" on the <zing-grid> tag (global) or individual <zg-column> tags, like so:

<zing-grid ...>
  <zg-colgroup>
    <!-- Inherits global 'default' styling -->
    <zg-column ...>
    <!-- Overrides to show tooltip as 'system' styling -->
    <zg-column ... header-tooltip-type="system">
  </zg-colgroup>
</zing-grid>

To individually set a column back to the default styling if you globally set them as the system style, set the column's attribute value to the default default: header-tooltip-type="default".

System tooltips are populated and styled via CSS :before and :after selectors (for the 'arrow' and 'text bubble', respectively) and no markup is actually inserted into the header cell. A limitation of this method is the CSS content property only accepts plain text. Any tag added to the content string will be rendered as text, not as the element. Therefore, only set header-tooltip-type="system" if your tooltips contain only text.

Top

Icon (Trigger)

By default, tooltips are added to the header cell and activated on cell hover. You can optionally add an information icon () to the cell to help alert the user to the tooltips' presence.

Set header-tooltip-trigger="icon" on the <zing-grid> tag (global) or individual <zg-column> tags, and the icon will appear on the right-side of the cell (you are able to change its positioning - see the section below).

If you need to individually set a column back to the default and hide the icon, set the column's attribute value to the default text: header-tooltip-trigger="text"

If you set the tooltip to use the system styling, the icon will not be available regardless of this attribute setting.

Information Icon Grid

Here is a complete grid with an information icon in the default right position of the header:

Icon Position

To orient the information icon's position within the header cell, use header-tooltip-icon-position on the grid or individual columns (see below) with one of 3 options:

  • right - The default. This can be omitted unless being set to override the grid's global setting.
  • left - The icon is positioned on the left edge of the cell, before the text.
  • after-text - The icon is placed after the cell's header text.
<zing-grid ... header-tooltip-trigger="icon" header-tooltip-icon-position="left">
  <zg-colgroup>
    <!-- (Default) Shows the icon, positioned on the left -->
    <zg-column ...></zg-column>
    <!-- Overrides to position the icon immediately after the header text -->
    <zg-column ... header-tooltip-icon-position="after-text"></zg-column>
    <!-- Overrides to hide the icon -->
    <zg-column ... header-tooltip-trigger="text"></zg-column>
  </zg-colgroup>
</zing-grid>
Top

Activation Type

Tooltips are shown on hover by default. To change the activation method to click instead, set header-tooltip-action="click" on the <zing-grid> tag (global) or individual <zg-column> tags (see below). Icons must be enabled for click activation to work.

<zing-grid ... header-tooltip-trigger="icon" header-tooltip-action="click">
  <zg-colgroup>
    <!-- Inherits global 'click' -->
    <zg-column ...>
    <!-- Overrides to 'hover' -->
    <zg-column ... header-tooltip-action="hover">
  </zg-colgroup>
</zing-grid>

Changing the activation type to click is only available when the icon is shown. Column sorting is activated by clicking the header cell, so it cannot also be used to show the tooltip. If you set the activation to click but forget to enable the icons, the tooltip will continue to show on hover but a <zg-status> alert will fire.

Top

Tooltip Position

By default, tooltips are revealed above the column header cell. To change the direction of the tooltip activation, set header-tooltip-position on the <zing-grid> tag (global) or individual <zg-column> tags (see below) with one of 4 options:

  • top - The default. This can be omitted unless being set to override the grid's global setting.
  • bottom
  • left
  • right
<zing-grid ... header-tooltip-position="right">
  <zg-colgroup>
    <!-- Inherits global 'right' position -->
    <zg-column ...>
    <!-- Overrides to reveal below the cell -->
    <zg-column ... header-tooltip-position="bottom">
  </zg-colgroup>
</zing-grid>

Custom Positioned Tooltips Grid

Here is a complete grid with tooltips displayed both below and to the left of the column header:

Top

Related Resources

Here are some extra resources related to this feature to help with creating your grid:

[features: column tooltips]