Widget API
Reference for the plugin widget path (TypeScript/Lit). For the custom-widget API, see Build your first custom widget.
The base class
Section titled “The base class”A widget shipped by a plugin extends OverlayHubWidget (from @teamhud/widget-mixins). It provides
drag, fling/snap-to-edge, toward-center panel placement, hover-reveal, edge-peek,
auto-collapse, and interactive-region sync. You implement three things (plus overlayRefreshHoveredVisual, which every hub overrides to mirror hover into state):
| Override | Returns | Purpose |
|---|---|---|
overlayRegionOwnerId() |
string |
Stable id this hub owns for click-through. |
overlayHubRegistryEntry() |
{ id, label, icon } |
The hub button — icon is inline SVG using currentColor. |
render() |
template | Mounts #hub-btn-mount and, when open, a <th-hub-panel> whose body is yours. |
Optional overrides you’ll commonly reach for: overlayPanelWidthPx(),
overlayPanelHeightPx(), overlayPanelAllowedSides(), and overlayRefreshHoveredVisual(hovered).
Mount the element from the bundle entry with mountCapableWidget('<tag>', context).
Building blocks
Section titled “Building blocks”@teamhud/widget-mixins—OverlayHubWidget,mountCapableWidget.@teamhud/ui-core— theth-*components (th-hub-panel,th-hub-panel-header, …) and the--th-*design tokens.@teamhud/overlay-positioning— the placement / drag / snap engine (used by the base class; you rarely call it directly).
Styling
Section titled “Styling”Everything visual reads from --th-* design tokens — never hardcode colors, fonts,
spacing, or motion. The full token catalog, the th-* component library, and the design
rules are in Theming & styling.
Contract checks
Section titled “Contract checks”Two guardrails fail the build if a widget hand-rolls drag/placement, uses retired palette
literals, or hardcodes a font family: pnpm check:widget-contract. Keep emit in dist/
(pnpm check:src-artifacts).