feat(widgets) Styled tooltips

Author: ibgreen

docs/api-reference/core/widget.md

@@ -91,6 +91,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.
+
 #### `onAdd` {#onadd}
 
 Required. Called when the widget is added to a Deck instance.

docs/api-reference/widgets/overview.md

@@ -133,6 +133,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).
 
+Bundled widgets render their control labels as themed tooltips instead of native browser tooltips. Custom widgets can use `updateWidgetTooltip` from `@deck.gl/widgets` in `onAfterRenderHTML()` to apply the same rendering to descendants with a `data-deck-widget-tooltip` attribute.
+
 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/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.
 
+Bundled widgets now render themed tooltips for their controls.
+
 ## deck.gl v9.3
 
 Release date: April 13, 2026

modules/core/src/lib/widget.ts

@@ -95,6 +95,7 @@ export abstract class Widget<
   updateHTML(): void {
     if (this.rootElement) {
       this.onRenderHTML(this.rootElement);
+      this.onAfterRenderHTML(this.rootElement);
     }
   }
 
@@ -144,6 +145,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/compass-widget.tsx

@@ -5,6 +5,7 @@
 import {Widget, FlyToInterpolator, WebMercatorViewport, _GlobeViewport} from '@deck.gl/core';
 import type {Viewport, WidgetPlacement, WidgetProps} from '@deck.gl/core';
 import {render} from 'preact';
+import {updateWidgetTooltip} from './lib/widget-tooltip';
 
 export type CompassWidgetProps = WidgetProps & {
   /** Widget positioning within the view. Default 'top-left'. */
@@ -30,6 +31,8 @@ export type CompassWidgetProps = WidgetProps & {
 };
 
 export class CompassWidget extends Widget<CompassWidgetProps> {
+  protected override onAfterRenderHTML = updateWidgetTooltip;
+
   static defaultProps: Required<CompassWidgetProps> = {
     ...Widget.defaultProps,
     id: 'compass',
@@ -69,7 +72,8 @@ export class CompassWidget extends Widget<CompassWidgetProps> {
               this.handleCompassReset(viewport);
             }
           }}
-          title={this.props.label}
+          aria-label={this.props.label}
+          data-deck-widget-tooltip={this.props.label}
           style={{transform: `rotateX(${rx}deg)`}}
         >
           <svg fill="none" width="100%" height="100%" viewBox="0 0 26 26">

modules/widgets/src/fullscreen-widget.tsx

@@ -5,6 +5,7 @@
 /* global document */
 import {log, Widget, type WidgetProps, type WidgetPlacement} from '@deck.gl/core';
 import {render} from 'preact';
+import {updateWidgetTooltip} from './lib/widget-tooltip';
 import {IconButton} from './lib/components/icon-button';
 
 /* eslint-enable max-len */
@@ -31,6 +32,8 @@ export type FullscreenWidgetProps = WidgetProps & {
 };
 
 export class FullscreenWidget extends Widget<FullscreenWidgetProps> {
+  protected override onAfterRenderHTML = updateWidgetTooltip;
+
   static defaultProps: Required<FullscreenWidgetProps> = {
     ...Widget.defaultProps,
     id: 'fullscreen',

modules/widgets/src/gimbal-widget.tsx

@@ -5,6 +5,7 @@
 import {Widget, LinearInterpolator} from '@deck.gl/core';
 import type {Viewport, WidgetPlacement, WidgetProps} from '@deck.gl/core';
 import {render} from 'preact';
+import {updateWidgetTooltip} from './lib/widget-tooltip';
 
 export type GimbalWidgetProps = WidgetProps & {
   placement?: WidgetPlacement;
@@ -31,6 +32,8 @@ export type GimbalWidgetProps = WidgetProps & {
 };
 
 export class GimbalWidget extends Widget<GimbalWidgetProps> {
+  protected override onAfterRenderHTML = updateWidgetTooltip;
+
   static defaultProps: Required<GimbalWidgetProps> = {
     ...Widget.defaultProps,
     id: 'gimbal',
@@ -71,7 +74,8 @@ export class GimbalWidget extends Widget<GimbalWidgetProps> {
               this.resetOrbitView(viewport);
             }
           }}
-          title={this.props.label}
+          aria-label={this.props.label}
+          data-deck-widget-tooltip={this.props.label}
           style={{position: 'relative', width: 26, height: 26}}
         >
           {/* Outer ring */}

modules/widgets/src/icon-widget.tsx

@@ -5,6 +5,7 @@
 import type {WidgetPlacement, WidgetProps} from '@deck.gl/core';
 import {render, type JSX} from 'preact';
 import {Widget} from '@deck.gl/core';
+import {updateWidgetTooltip} from './lib/widget-tooltip';
 import {IconButton} from './lib/components/icon-button';
 
 export type IconWidgetProps = WidgetProps & {
@@ -26,6 +27,8 @@ export type IconWidgetProps = WidgetProps & {
  * A generic widget that displays a button with icon or text content.
  */
 export class IconWidget extends Widget<IconWidgetProps> {
+  protected override onAfterRenderHTML = updateWidgetTooltip;
+
   static defaultProps: Required<IconWidgetProps> = {
     ...Widget.defaultProps,
     id: 'icon',

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/components/icon-button.tsx

@@ -32,7 +32,8 @@ export const IconButton = (props: IconButtonProps) => {
         className={`deck-widget-icon-button ${className}`}
         type="button"
         onClick={onClick}
-        title={label}
+        aria-label={label}
+        data-deck-widget-tooltip={label}
       >
         {children ? children : <div className="deck-widget-icon" style={iconStyle} />}
       </button>