TooltipPlugin

Since v1.28.0

Tooltip Plugin for tbw-grid

Shows styled popover tooltips when header or cell text overflows its container. Uses the Popover API with CSS anchor positioning for consistent themed appearance across light and dark modes.

Installation

import { TooltipPlugin } from '@toolbox-web/grid/plugins/tooltip';

Configuration Options

Option	Type	Description
header?	boolean	Enable automatic header tooltips when text overflows. Individual columns can override with headerTooltip.
cell?	boolean	Enable automatic cell tooltips when text overflows. Individual columns can override with cellTooltip.
focus?	boolean	Show the tooltip for the focused cell during keyboard navigation, so truncated content is reachable without a pointer — WCAG 2.2 SC 1.4.13 Content on Hover or Focus.
hideDelay?	number	Grace period in milliseconds before a tooltip hides once the pointer leaves its cell. Gives the pointer time to travel onto the tooltip itself, which SC 1.4.13 requires so its content can be read, magnified, or selected. Set to 0 to hide immediately.

Examples

Default — auto-tooltip on overflow

grid.gridConfig = {
  plugins: [new TooltipPlugin()],
};

Header-only tooltips

grid.gridConfig = {
  plugins: [new TooltipPlugin({ cell: false })],
};

Per-column overrides

grid.gridConfig = {
  columns: [
    { field: 'name', cellTooltip: (ctx) => `${ctx.row.first} ${ctx.row.last}` },
    { field: 'actions', cellTooltip: false },
    { field: 'revenue', headerTooltip: 'Total revenue in USD (before tax)' },
  ],
  plugins: [new TooltipPlugin()],
};

Accessibility

Conforms to WCAG 2.2 SC 1.4.13 (Content on Hover or Focus) out of the box: the tooltip is dismissible with Escape, hoverable (the pointer can rest on it to read or copy the text), persistent (never hidden on a timer), and appears on keyboard focus as cell focus moves. Pointer interaction never triggers the focus path, so mouse behaviour is unchanged. See TooltipConfig.focus and TooltipConfig.hideDelay to tune it.

Extends BaseGridPlugin

Inherited methods like attach(), detach(), afterRender(), etc. are documented in the base class.

Properties

Property	Type	Description
name	tooltip	Unique plugin identifier (derived from class name by default)
styles	string	CSS styles to inject via document.adoptedStyleSheets
manifest	PluginManifest<TooltipConfig>	Plugin manifest - declares owned properties, config rules, and hook priorities.

Property Details

manifest

Plugin manifest - declares owned properties, config rules, and hook priorities.

This is read by the configuration validator to:

• Validate that required plugins are loaded when their properties are used
• Execute configRules to detect invalid/conflicting settings
• Order hook execution based on priority

static override readonly manifest: PluginManifest<MyConfig> = {
  ownedProperties: [
    { property: 'myProp', level: 'column', description: 'the "myProp" column property' },
  ],
  configRules: [
    { id: 'myPlugin/conflict', severity: 'warn', message: '...', check: (c) => c.a && c.b },
  ],
};

---

Methods

attach()

override — Called when the plugin is attached to a grid. Override to set up event listeners, initialize state, etc.

attach(grid: GridElement): void

Parameters

Name	Type	Description
grid	GridElement

Example

attach(grid: GridElement): void {
  super.attach(grid);
  // Set up document-level listeners with auto-cleanup
  document.addEventListener('keydown', this.handleEscape, {
    signal: this.disconnectSignal
  });
}

---

detach()

override — Called when the plugin is detached from a grid. Override to clean up event listeners, timers, etc.

detach(): void

Example

detach(): void {
  // Clean up any state not handled by disconnectSignal
  this.selectedRows.clear();
  this.cache = null;
}

---

afterRender()

override — Called after each render cycle completes. Use this for DOM manipulation, adding event listeners to rendered elements, or applying visual effects like selection highlights.

afterRender(): void

Example

afterRender(): void {
  // Apply selection styling to rendered rows
  const rows = this.gridElement?.querySelectorAll('.data-grid-row');
  rows?.forEach((row, i) => {
    row.classList.toggle('selected', this.selectedRows.has(i));
  });
}

---