hb-pad-joystick — integrator guide

Category: utilities · Tags: utilities, controls · Package: @htmlbricks/hb-pad-joystick

Summary

hb-pad-joystick is a touch-friendly directional control for games, kiosks, or remote UIs. It renders either a four-way D-pad (discrete presses) or an analog joystick (html5-joystick-new) that streams stick position and a coarse cardinal direction.

Behavior

| Mode | pad_or_joystick | Interaction | Events | |------|-------------------|---------------|--------| | D-pad (default) | omitted or dpad | Four <button> tiles | sendDirection | | Joystick | joystick | Drag in the stick zone | sendJoystickPosition |

Other pad_or_joystick values show a small “Unknown type” placeholder.

Custom element tag

<hb-pad-joystick …></hb-pad-joystick>

Attributes (HTML / reflected props)

Strings only from HTML; pass joystick_parameters as a JSON string.

| Attribute | Role | |-----------|------| | id | Echoed on every event detail.id. | | style | Optional inline host style (typed on Component). | | pad_or_joystick | dpad | joystick (default dpad). | | joystick_parameters | JSON object: internalFillColor, internalStrokeColor, externalStrokeColor, internalLineWidth, externalLineWidth (joystick mode only). |

Events

| Event | detail | |-------|----------| | sendDirection | { direction: "up" \| "right" \| "down" \| "left"; id: string } | | sendJoystickPosition | { x: number; y: number; cardinalDirection: CardinalDirection; id: string } |

CSS custom properties, parts, and slots

D-pad skin uses --hb-pad-joystick-size, --dpad-*, --arrowcolor, --tri-* tokens documented in extra/docs.ts. Defaults align with Bulma scheme variables; see Bulma CSS variables.

::part: none on this host. Slots: none.

TypeScript typings (authoring)

See types/webcomponent.type.d.ts for Component, CardinalDirection, and Events.

Minimal HTML

<hb-pad-joystick id="player-1"></hb-pad-joystick>

Joystick with custom colors:

<hb-pad-joystick
  id="cam-ptz"
  pad_or_joystick="joystick"
  joystick_parameters='{"internalFillColor":"#485fc7","internalStrokeColor":"#363636","externalStrokeColor":"#b5b5b5"}'
></hb-pad-joystick>