Skip to content
TeamHUD Docs

Widgets

A TeamHUD widget renders on a click-through overlay as a hub button that opens a panel. The overlay is click-through by default; a widget registers interactive regions so clicks land on it and nowhere else.

Two behaviors are part of every widget, not optional polish:

  • Interactive regions — the hub (always) and the panel (while open) tell the overlay where to accept clicks. Keep them in sync as the widget resizes or opens menus.
  • Auto-collapse — an open panel closes when the pointer leaves, on outside click, and on Escape. Panels are transient, not sticky.

How much you implement depends on the path:

  • Custom widgets get the hub, panel chrome, drag, and auto-collapse for free — you write only the panel’s HTML/CSS/JS. See Build your first custom widget.
  • Plugin widgets extend a shared base class (OverlayHubWidget) that provides drag, toward-center placement, hover-reveal, and region sync; you implement the hub button and the panel body. See Build your first plugin and the Widget API reference.

Both read the same --th-* design tokens for color, type, spacing, and motion, so widgets match the HUD by construction — never hardcode colors, fonts, or animation timings.