tooltips.md

Widget Tooltips

Built-in button widgets ship with styled tooltips that appear on hover and keyboard focus. These replace the slow native browser title tooltips with themed, customizable alternatives.

Customizing Built-in Tooltips

label vs tooltip

The label prop sets the button's accessible name (aria-label) and is always a plain string. By default, the tooltip displays the label text. The tooltip prop overrides only the visual tooltip — use it for rich HTML content, a different display string, or false to hide the tooltip while preserving accessibility.

Overriding tooltip text

Each button widget accepts a tooltip prop that overrides the default label:

new ZoomWidget({ zoomInTooltip: 'Zoom In (Ctrl+Plus)' })
new FullscreenWidget({ enterTooltip: 'Go Fullscreen (F)' })

Overriding with custom HTML

For rich content (e.g. keyboard shortcut badges), pass an HTMLElement:

const tip = document.createElement('span');
tip.innerHTML = 'Zoom In <kbd>⌘+</kbd>';
new ZoomWidget({ zoomInTooltip: tip })

Disabling tooltips

Pass false to suppress the tooltip for a specific button:

new ZoomWidget({ zoomInTooltip: false })
new CompassWidget({ tooltip: false })

Styling tooltips

Tooltip appearance inherits the widget theme via CSS variables. You can customize them globally or per-widget:

.deck-widget {
  --tooltip-max-width: 300px;
  --tooltip-z-index: 2000;
}

Name	Type	Default
--tooltip-max-width	Dimension	240px
--tooltip-z-index	Number	1000

Tooltips also inherit the following menu variables: --menu-background, --menu-shadow, --menu-backdrop-filter, --menu-text.

Writing Tooltips in Custom Widgets

Using Preact (with _Tooltip component)

If your custom widget uses Preact for rendering, import the _Tooltip component:

import {_Tooltip as Tooltip} from '@deck.gl/widgets';
import {render} from 'preact';

class MyWidget extends Widget {
  className = 'my-widget';
  placement = 'top-left';

  onRenderHTML(rootElement) {
    render(
      <Tooltip content="My tooltip text">
        <button aria-label="My Action" onClick={...}>
          Do thing
        </button>
      </Tooltip>,
      rootElement
    );
  }
}

TooltipProps

Prop	Type	Default	Description
content	string | ComponentChildren	—	Tooltip content to display
placement	Placement	'right'	Position relative to the trigger (uses @floating-ui/dom placement values)
children	ComponentChildren	—	The trigger element

Without Preact (CSS class + your own logic)

For custom widgets using vanilla JS, React, or any other framework, implement your own show/hide behavior and apply the .deck-widget-tooltip CSS class to get consistent theming:

class MyWidget extends Widget {
  className = 'my-widget';
  placement = 'top-left';

  onRenderHTML(rootElement) {
    const btn = document.createElement('button');
    btn.setAttribute('aria-label', 'My Action');
    btn.setAttribute('aria-describedby', 'my-tooltip');

    const tooltip = document.createElement('div');
    tooltip.id = 'my-tooltip';
    tooltip.className = 'deck-widget-tooltip';
    tooltip.setAttribute('role', 'tooltip');
    tooltip.textContent = 'My Action';
    tooltip.hidden = true;

    btn.addEventListener('pointerenter', () => { tooltip.hidden = false; });
    btn.addEventListener('pointerleave', () => { tooltip.hidden = true; });

    rootElement.replaceChildren(btn, tooltip);
  }
}

The .deck-widget-tooltip class provides themed background, shadow, text color, font, border-radius, and max-width — matching the rest of the widget UI. You are responsible for:

• Positioning (consider @floating-ui/dom or CSS anchor positioning)
• Show/hide behavior (pointer events, focus, keyboard dismiss)

Accessibility

Built-in widget tooltips follow these accessibility practices:

• Buttons use aria-label for screen reader announcements
• Tooltip elements have role="tooltip"
• Tooltips appear on keyboard focus
• Pressing Escape dismisses the tooltip

Custom widget authors should follow the same patterns.