Tooltip Plugin

The Tooltip plugin shows popover tooltips when header or cell text overflows its container. It uses the Popover API with CSS anchor positioning for a native, consistent experience across browsers — with a JavaScript fallback for older browsers.

Tooltips appear automatically on hover. Per-column overrides let you provide custom static text or dynamic content derived from row data.

Installation

import '@toolbox-web/grid/features/tooltip';

Basic Usage

TypeScript

import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/tooltip';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'id', header: 'ID', width: 60 },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email Address' },
    { field: 'department', header: 'Department / Division' },
  ],
  features: { tooltip: true },
};

React

import '@toolbox-web/grid-react/features/tooltip';
import { DataGrid } from '@toolbox-web/grid-react';
import type { GridConfig } from '@toolbox-web/grid-react';

const gridConfig: GridConfig = {
  columns: [
    { field: 'id', header: 'ID', width: 60 },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email Address' },
  ],
  features: { tooltip: true },
};

function App({ data }) {
  return <DataGrid rows={data} gridConfig={gridConfig} style={{ height: '400px' }} />;
}

Alternative: feature prop

You can instead pass columns={[ … ]} and tooltip as individual props on <DataGrid>. That form is idiomatic React, but gridConfig keeps the configuration identical across every framework.

Vue

<script setup>
import '@toolbox-web/grid-vue/features/tooltip';
import { TbwGrid } from '@toolbox-web/grid-vue';
import type { GridConfig } from '@toolbox-web/grid-vue';

const gridConfig: GridConfig = {
  columns: [
    { field: 'id', header: 'ID', width: 60 },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email Address' },
  ],
  features: { tooltip: true },
};
</script>

<template>
  <TbwGrid :rows="data" :grid-config="gridConfig" style="height: 400px" />
</template>

Alternative: prop + light-dom columns

You can instead bind tooltip and declare columns with <TbwGridColumn> children. That form is idiomatic Vue, but gridConfig keeps the configuration identical across every framework.

Angular

import '@toolbox-web/grid-angular/features/tooltip';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { GridConfig } from '@toolbox-web/grid-angular';

@Component({
  selector: 'app-grid',
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="rows"
      [gridConfig]="gridConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class GridComponent {
  rows = [];
  gridConfig: GridConfig = {
    columns: [
      { field: 'id', header: 'ID', width: 60 },
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email Address' },
    ],
    features: { tooltip: true },
  };
}

Alternative: per-feature directive

You can instead import GridTooltipDirective and bind [tooltip] directly on <tbw-grid>. That form gives a compile-time check that the feature is imported, but gridConfig.features above is the recommended, framework-consistent approach.

Demos

Hover over truncated column headers or cell values to see tooltips. Toggle header/cell tooltips with the controls. The Job Title column demonstrates a custom headerTooltip string and a dynamic cellTooltip function.

TOOLTIP

Header tooltipsShow tooltips when header text overflows

Cell tooltipsShow tooltips when cell text overflows

Show source

Configuration Options

Option	Type	Default	Description
header	boolean	true	Enable automatic tooltips on overflowing header text
cell	boolean	true	Enable automatic tooltips on overflowing cell text
focus	boolean	true	Show the tooltip for the focused cell during keyboard navigation. Pointer interaction is unaffected.
hideDelay	number	120	Grace period in milliseconds before the tooltip hides once the pointer leaves the cell, so it can be moved onto the tooltip itself. 0 hides immediately.

Per-Column Overrides

Override tooltip behavior on individual columns with headerTooltip and cellTooltip:

const columns = [
  // Static header tooltip
  { field: 'revenue', header: 'Rev.', headerTooltip: 'Total revenue in USD (before tax)' },

  // Dynamic cell tooltip that adds context beyond the cell value
  { field: 'name', cellTooltip: (ctx) => `Hired ${new Date(ctx.row.hireDate).toLocaleDateString()}` },

  // Disable tooltip for a specific column
  { field: 'actions', cellTooltip: false, headerTooltip: false },
];

Tip

If the cell value itself isn’t a plain row[field] read (for example, a “Full Name” computed from firstName + lastName), use valueAccessor on the column rather than computing it inside cellTooltip. The accessor runs once per row and is reused by sorting, filtering, exports, and the default tooltip — cellTooltip only adds extra information beyond the cell’s value.

Property	Type	Description
headerTooltip	false | string | (ctx) => string | null	Override header tooltip. false disables it, a string sets static text, a function returns dynamic text (return null to suppress).
cellTooltip	false | string | (ctx) => string | null	Override cell tooltip. Same signature as headerTooltip. The callback receives { value, row, field, column }.

Styling

The tooltip is placed above the anchor cell whenever it fits there, and drops below only when the space above the cell is too small. A directional arrow points at the anchor and flips with the placement. It supports CSS custom properties:

Property	Default	Description
--tbw-tooltip-bg	light-dark(#333338, #484850)	Tooltip background color
--tbw-tooltip-fg	light-dark(#f5f5f5, #f0f0f0)	Tooltip text color
--tbw-tooltip-border	light-dark(#222226, #6a6a72)	Tooltip border and arrow color
--tbw-tooltip-shadow	drop-shadow(0 4px 4px rgba(0,0,0,.45))	Tooltip shadow (a filter value, so it follows the arrow)
--tbw-tooltip-radius	var(--tbw-border-radius)	Border radius
--tbw-tooltip-max-width	300px	Maximum width before the text wraps
--tbw-tooltip-arrow-size	14px	Size of the arrow’s (pre-rotation) box
--tbw-tooltip-arrow-offset	16px	Horizontal offset of the arrow from the left edge

Accessibility

The plugin satisfies WCAG 2.2 SC 1.4.13 Content on Hover or Focus:

• Dismissible — Escape hides a visible tooltip from anywhere on the page, without moving the pointer. The key is not consumed, so it still cancels an in-progress cell edit.
• Hoverable — the tooltip stays up for hideDelay milliseconds after the pointer leaves the cell, and indefinitely while the pointer rests on the tooltip itself. Its text is selectable, so long content can be read with a screen magnifier or copied.
• Persistent — the tooltip is never dismissed on a timer; it hides only when the pointer or keyboard focus moves away, or on Escape.
• Focus-triggered — arrowing onto a truncated cell shows its tooltip, so keyboard users can read content a mouse user would hover for. The anchor cell is linked to the popover via aria-describedby, and the popover carries role="tooltip".

The focus path is driven by key presses, so it only ever runs for keyboard navigation — clicking a cell with a pointer never triggers it. Set focus: false to opt out entirely (this forfeits the SC 1.4.13 “focus” path).

No browser configuration required

Nothing has to be enabled in the browser or the operating system. There is deliberately no web API that reports whether a visitor uses assistive technology (browsers refuse to expose one because it is a fingerprinting and discrimination vector), so the plugin infers intent from input modality instead: the tooltip appears whenever a navigation key moves the cell focus. Just click into the grid and press an arrow key.

See Also

• Plugins Overview — all available plugins
• Context Menu — another popover-based plugin
• Responsive — card layout on narrow containers

tbw-grid {
  --tbw-tooltip-bg: #1e1e2e;
  --tbw-tooltip-fg: #cdd6f4;
  --tbw-tooltip-border: #45475a;
}