feat(widgets): styled tooltips

docs/api-reference/core/widget.md

@@ -39,6 +39,12 @@ Additional inline CSS styles on the top HTML element of the widget. camelCase CS
 
 Additional CSS classnames on the top HTML element.
 
+#### `onAfterRenderHTML` (function, optional) {#onafterrenderhtml-prop}
+
+Called after the widget has rendered HTML into its root element. Receives the root `HTMLElement`.
+
+If a widget subclass implements the protected `onAfterRenderHTML()` method, that method runs before this callback.
+
 #### `_container` (string | HTMLDivElement, optional) {#_container}
 
 Experimental. The container that this widget is being attached to. Default to `viewId`.
@@ -91,6 +97,10 @@ Updates the widget. Called by the specific widget when state has changed. Calls
 
 This function is implemented by the specific widget subclass to update the HTML for the widget
 
+#### `onAfterRenderHTML` {#onafterrenderhtml}
+
+Optional. Called after `onRenderHTML()` has updated the widget HTML, and before the `onAfterRenderHTML` prop callback.
+
 #### `onAdd` {#onadd}
 
 Required. Called when the widget is added to a Deck instance.

docs/api-reference/widgets/overview.md

@@ -42,6 +42,7 @@ This module contains the following widgets:
 - [ScreenshotWidget](./screenshot-widget.md)
 - [StatsWidget](./stats-widget.md)
 - [ThemeWidget](./theme-widget.md)
+- [Widget Tooltip](./widget-tooltip.md)
 
 ## Installation
 
@@ -133,6 +134,8 @@ new Deck({
 
 Widgets with UI (e.g. a button or panel) can be positioned relative to the deck.gl view they are controlling, via the `viewId` and `placement` props. See [WidgetProps](../core/widget.md#widgetprops).
 
+Custom widgets can opt into [themed text tooltips](./widget-tooltip.md) by calling `updateWidgetTooltip` from `@deck.gl/widgets` in `onAfterRenderHTML()`.
+
 The `viewId` controls which HTML container will mount to, and the `placement` prop will position it relative to the container it is in, like so:
 
 ```ts

docs/api-reference/widgets/widget-tooltip.md

@@ -0,0 +1,57 @@
+# Widget Tooltip
+
+`updateWidgetTooltip` adds delegated, theme-aware text tooltips to a custom widget. It is opt-in and does not change the behavior of bundled widgets.
+
+```ts
+import {Widget} from '@deck.gl/core';
+import {updateWidgetTooltip} from '@deck.gl/widgets';
+import {render} from 'preact';
+import '@deck.gl/widgets/stylesheet.css';
+```
+
+## Usage
+
+Pass `updateWidgetTooltip` as the `onAfterRenderHTML` prop. Descendants with a `data-deck-widget-tooltip` attribute become tooltip anchors.
+
+```tsx
+class ResetWidget extends Widget {
+  onRenderHTML(rootElement: HTMLElement) {
+    render(
+      <button
+        aria-label="Reset view"
+        data-deck-widget-tooltip="Reset view"
+        onClick={() => this.resetView()}
+      >
+        Reset
+      </button>,
+      rootElement
+    );
+  }
+}
+
+const widget = new ResetWidget({
+  onAfterRenderHTML: updateWidgetTooltip
+});
+```
+
+Subclassing remains available when a custom widget always needs the helper:
+
+```ts
+protected override onAfterRenderHTML = updateWidgetTooltip;
+```
+
+Tooltip labels are plain text. Set `aria-label` separately when the anchor needs an accessible name, such as an icon-only button. If an anchor also has a native `title`, the helper removes it to avoid competing browser tooltips. The helper shows tooltips on pointer hover and keyboard focus, and hides them on pointer leave, blur, Escape, or the next render.
+
+## `updateWidgetTooltip`
+
+Installs delegated tooltip event handling on a widget root and removes any visible tooltip from the previous render.
+
+Parameters:
+
+- `rootElement` (`HTMLElement`) - Widget root containing elements with `data-deck-widget-tooltip`.
+
+The `.deck-widget-tooltip` style uses the standard widget theme variables. Applications may override `--tooltip-max-width` and `--tooltip-z-index` when needed.
+
+## Source
+
+[modules/widgets/src/lib/widget-tooltip.ts](https://github.com/visgl/deck.gl/tree/master/modules/widgets/src/lib/widget-tooltip.ts)

docs/whats-new.md

@@ -41,6 +41,8 @@ Release date: TBD
 
 A new experimental `ViewLayout` system with a helper function `buildViewsFromViewLayout()` allows advanced nested and relative view layouts to be specified using a declarative layout tree.
 
+The new `updateWidgetTooltip` helper lets custom widgets opt into themed text tooltips.
+
 ## deck.gl v9.3
 
 Release date: April 13, 2026

modules/core/src/lib/widget.ts

@@ -18,6 +18,8 @@ export type WidgetProps = {
   style?: Partial<CSSStyleDeclaration>;
   /** Additional CSS class. */
   className?: string;
+  /** Called after the widget has rendered HTML into its root element. */
+  onAfterRenderHTML?: (rootElement: HTMLElement) => void;
   /**
    * The container that this widget is being attached to. Default to `viewId`.
    * If set to `'root'`, the widget is placed relative to the whole deck.gl canvas.
@@ -35,7 +37,8 @@ export abstract class Widget<
     id: 'widget',
     style: {},
     _container: null,
-    className: ''
+    className: '',
+    onAfterRenderHTML: undefined!
   };
 
   /** Unique identifier of the widget. */
@@ -95,6 +98,8 @@ export abstract class Widget<
   updateHTML(): void {
     if (this.rootElement) {
       this.onRenderHTML(this.rootElement);
+      this.onAfterRenderHTML(this.rootElement);
+      this.props.onAfterRenderHTML?.(this.rootElement);
     }
   }
 
@@ -144,6 +149,9 @@ export abstract class Widget<
   /** Called to render HTML into the root element */
   abstract onRenderHTML(rootElement: HTMLElement): void;
 
+  /** Overridable by subclass - called after HTML is rendered into the root element. */
+  protected onAfterRenderHTML(rootElement: HTMLElement): void {}
+
   /** Internal API called by Deck when the widget is first added to a Deck instance */
   _onAdd(params: {deck: Deck<any>; viewId: string | null}): HTMLDivElement {
     return this.onAdd(params) ?? this.onCreateRootElement();

modules/widgets/src/index.ts

@@ -62,6 +62,7 @@ export type {ContentBounds, ScrollbarWidgetProps, ScrollbarDecoration} from './s
 
 export {LightTheme, DarkTheme, LightGlassTheme, DarkGlassTheme} from './themes';
 export type {DeckWidgetTheme} from './themes';
+export {updateWidgetTooltip} from './lib/widget-tooltip';
 
 // Experimental preact components
 export {ButtonGroup as _ButtonGroup, type ButtonGroupProps} from './lib/components/button-group';

modules/widgets/src/lib/widget-tooltip.ts

@@ -0,0 +1,103 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+const TOOLTIP_ATTR = 'data-deck-widget-tooltip';
+const OFFSET = 8;
+const widgetTooltips = new WeakMap<HTMLElement, WidgetTooltip>();
+
+/** Updates delegated tooltip handling after a widget renders its HTML. */
+export function updateWidgetTooltip(rootElement: HTMLElement): void {
+  for (const target of rootElement.querySelectorAll(`[${TOOLTIP_ATTR}][title]`)) {
+    target.removeAttribute('title');
+  }
+
+  let tooltip = widgetTooltips.get(rootElement);
+  if (!tooltip) {
+    tooltip = new WidgetTooltip();
+    widgetTooltips.set(rootElement, tooltip);
+  }
+  tooltip.update(rootElement);
+}
+
+class WidgetTooltip {
+  private element: HTMLDivElement | null = null;
+  private listenerRoot: HTMLElement | null = null;
+
+  update(root: HTMLElement): void {
+    this.hide();
+    if (this.listenerRoot === root) return;
+
+    this.listenerRoot = root;
+    root.addEventListener('pointerover', this.onPointerOver);
+    root.addEventListener('pointerout', this.onPointerOut);
+    root.addEventListener('focusin', this.onFocusIn);
+    root.addEventListener('focusout', this.onFocusOut);
+    root.addEventListener('keydown', this.onKeyDown);
+  }
+
+  private hide(): void {
+    this.element?.remove();
+    this.element = null;
+  }
+
+  private onPointerOver = (event: PointerEvent): void => {
+    const target = this.getTarget(event.target);
+    if (target) this.show(target);
+  };
+
+  private onPointerOut = (event: PointerEvent): void => {
+    const target = this.getTarget(event.target);
+    if (target && !(event.relatedTarget instanceof Node && target.contains(event.relatedTarget))) {
+      this.hide();
+    }
+  };
+
+  private onFocusIn = (event: FocusEvent): void => {
+    const target = this.getTarget(event.target);
+    if (target?.matches(':focus-visible')) this.show(target);
+  };
+
+  private onFocusOut = (): void => this.hide();
+
+  private onKeyDown = (event: KeyboardEvent): void => {
+    if (event.key === 'Escape') this.hide();
+  };
+
+  private getTarget(target: EventTarget | null): HTMLElement | null {
+    const anchor = target instanceof Element ? target.closest(`[${TOOLTIP_ATTR}]`) : null;
+    return anchor instanceof HTMLElement ? anchor : null;
+  }
+
+  private show(anchor: HTMLElement): void {
+    const text = anchor.getAttribute(TOOLTIP_ATTR);
+    const root = this.listenerRoot;
+    if (!text || !root) return;
+
+    this.hide();
+    const tooltip = document.createElement('div');
+    tooltip.className = 'deck-widget-tooltip';
+    tooltip.setAttribute('role', 'tooltip');
+    tooltip.append(document.createTextNode(text));
+
+    root.append(tooltip);
+    this.element = tooltip;
+    this.position(anchor, tooltip, root);
+  }
+
+  private position(anchor: HTMLElement, tooltip: HTMLDivElement, root: HTMLElement): void {
+    const anchorRect = anchor.getBoundingClientRect();
+    const rootRect = root.getBoundingClientRect();
+    const tooltipRect = tooltip.getBoundingClientRect();
+    const right = anchorRect.right + OFFSET;
+    const left =
+      right + tooltipRect.width <= window.innerWidth
+        ? right
+        : anchorRect.left - tooltipRect.width - OFFSET;
+
+    tooltip.style.left = `${left - rootRect.left}px`;
+    tooltip.style.top = `${
+      anchorRect.top - rootRect.top + (anchorRect.height - tooltipRect.height) / 2
+    }px`;
+  }
+}

modules/widgets/src/stylesheet.css

@@ -1,4 +1,5 @@
 .deck-widget {
+  position: relative;
   margin: var(--widget-margin, 12px);
   box-sizing: border-box;
 }
@@ -105,6 +106,25 @@
   z-index: 100;
 }
 
+.deck-widget-tooltip {
+  position: absolute;
+  z-index: var(--tooltip-z-index, 1000);
+  pointer-events: none;
+  box-sizing: border-box;
+  max-width: var(--tooltip-max-width, 240px);
+  padding: 4px 8px;
+  border: var(--menu-border, unset);
+  border-radius: calc(var(--button-corner-radius, 8px) - 2px);
+  box-shadow: var(--menu-shadow, 0px 0px 8px 0px rgba(0, 0, 0, 0.25));
+  background: var(--menu-background, #fff);
+  backdrop-filter: var(--menu-backdrop-filter, unset);
+  color: var(--menu-text, rgb(24, 24, 26));
+  font-size: 12px;
+  line-height: 16px;
+  white-space: normal;
+  overflow-wrap: break-word;
+}
+
 /* Fullscreen styles */
 .deck-widget.deck-widget-fullscreen button.deck-widget-fullscreen-enter .deck-widget-icon {
   mask-image: var(

test/modules/core/lib/widget-manager.spec.ts

@@ -54,6 +54,27 @@ const mockDeckInstance = {
   height: 400
 };
 
+test('Widget#onAfterRenderHTML prop runs after protected hook', () => {
+  const calls: string[] = [];
+  class AfterRenderWidget extends TestWidget {
+    override onRenderHTML(): void {
+      calls.push('render');
+    }
+
+    protected override onAfterRenderHTML(): void {
+      calls.push('hook');
+    }
+  }
+
+  const widget = new AfterRenderWidget({
+    onAfterRenderHTML: () => calls.push('prop')
+  });
+  widget.rootElement = document.createElement('div');
+  widget.updateHTML();
+
+  expect(calls).toEqual(['render', 'hook', 'prop']);
+});
+
 test('WidgetManager#setProps', () => {
   const container = document.createElement('div');
   const widgetManager = new WidgetManager({deck: mockDeckInstance, parentElement: container});

test/modules/widgets/widget-tooltip.spec.ts

@@ -0,0 +1,74 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {afterEach, test, expect} from 'vitest';
+import {updateWidgetTooltip} from '@deck.gl/widgets';
+
+let rootElement: HTMLDivElement | undefined;
+
+afterEach(() => {
+  rootElement?.remove();
+  rootElement = undefined;
+});
+
+function createTooltipTarget(label: string) {
+  rootElement = document.createElement('div');
+  rootElement.className = 'deck-widget';
+
+  const button = document.createElement('button');
+  button.setAttribute('data-deck-widget-tooltip', label);
+  button.setAttribute('aria-label', label);
+  button.title = label;
+
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+  svg.append(path);
+  button.append(svg);
+  rootElement.append(button);
+  document.body.append(rootElement);
+  updateWidgetTooltip(rootElement);
+
+  return {button, path};
+}
+
+function dispatchPointerOver(element: Element): void {
+  element.dispatchEvent(new PointerEvent('pointerover', {bubbles: true}));
+}
+
+function dispatchPointerOut(element: Element): void {
+  element.dispatchEvent(new PointerEvent('pointerout', {bubbles: true}));
+}
+
+test('updateWidgetTooltip shows and hides themed text tooltips', () => {
+  const {button} = createTooltipTarget('Zoom In');
+  expect(button.title).toBe('');
+
+  dispatchPointerOver(button);
+  expect(rootElement?.querySelector('.deck-widget-tooltip')?.textContent).toBe('Zoom In');
+  dispatchPointerOut(button);
+  expect(rootElement?.querySelector('.deck-widget-tooltip')).toBe(null);
+
+  button.focus();
+  expect(rootElement?.querySelector('.deck-widget-tooltip')?.textContent).toBe('Zoom In');
+  button.dispatchEvent(new KeyboardEvent('keydown', {key: 'Escape', bubbles: true}));
+  expect(rootElement?.querySelector('.deck-widget-tooltip')).toBe(null);
+
+  button.blur();
+  button.focus();
+  expect(rootElement?.querySelector('.deck-widget-tooltip')?.textContent).toBe('Zoom In');
+  button.blur();
+  expect(rootElement?.querySelector('.deck-widget-tooltip')).toBe(null);
+});
+
+test('updateWidgetTooltip resolves SVG targets and updated labels', () => {
+  const {button, path} = createTooltipTarget('Reset north');
+
+  dispatchPointerOver(path);
+  expect(rootElement?.querySelector('.deck-widget-tooltip')?.textContent).toBe('Reset north');
+
+  button.setAttribute('data-deck-widget-tooltip', 'Reset view');
+  updateWidgetTooltip(rootElement!);
+  dispatchPointerOver(button);
+  expect(rootElement?.querySelector('.deck-widget-tooltip')?.textContent).toBe('Reset view');
+});