hb-tooltip — integrator guide

Category: overlays · Tags: overlays, tooltip · Package: @htmlbricks/hb-tooltip

Web component that wraps your light-DOM content in a trigger region and shows a floating tooltip bubble next to it. Positioning uses Floating UI (flip, shift, arrow, fixed offset). The bubble is styled like a classic dark tooltip and can be tuned with Bulma CSS variables and an optional inline style block inside the tooltip JSON.

Overview

• Default slot: Put buttons, links, icons, or short text here. The tooltip opens when the user hovers or focuses the trigger wrapper (not on click alone).
• tooltip: Pass a JSON string with at least title. Optional fields control placement, HTML rendering, two-line title/description layout, size limits, and per-tooltip colors.
• show: When set, visibility is controlled from the outside; hover/focus no longer toggles it. Omit show for fully interactive mode.
• visualizationChange: Fires whenever the tooltip becomes visible or hidden, including under programmatic show.

Disabled form controls inside the slot do not receive pointer events; the host still receives hover so the tooltip can appear over disabled buttons/inputs.

Custom element

hb-tooltip

Attributes

Names are snake_case. In HTML, attribute values are always strings.

| Attribute | Required | Description | | --- | --- | --- | | id | No | Echoed on visualizationChange as detail.id (empty string if unset). | | style | No | Standard host inline style string. | | tooltip | No | JSON string describing the tooltip (see Tooltip JSON). Invalid JSON logs a warning and yields no bubble content. | | show | No | Controls visibility when present. Accepted truthy strings: yes, true, 1, on. Falsy: no, false, 0, off. When omitted, visibility follows hover/focus only. |

Tooltip JSON

Deserialize the tooltip attribute to an object with this shape (TypeScript names as in types/webcomponent.type.d.ts):

Required

| Field | Type | Description | | --- | --- | --- | | title | string | Main text. If html is true, parsed as HTML (use only with trusted content). If description is set, title is shown as a bold heading and description as body text. |

Optional (supported by this build)

| Field | Type | Description | | --- | --- | --- | | description | string | Second block below title (plain text). Enables two-block layout and a default max-width of 200px unless you override maxWidth. | | placement | "auto" \| "top" \| "bottom" \| "left" \| "right" | Preferred side relative to the trigger. "auto" is treated like "top" for positioning. Floating UI may flip/shift to stay in view. | | html | boolean | When true, title is rendered with {@html ...} (XSS risk if content is user-controlled). | | style | TooltipStyle | Inline look for this instance (see below). | | maxWidth | string | CSS max-width on the bubble (e.g. "200px"). | | maxHeight | string | CSS max-height on the bubble. |

TooltipStyle

| Field | Description | | --- | --- | | backgroundColor | Bubble background (also drives --tooltip-bg for the arrow). Default in code: "black". | | color | Text color. Default: "white". | | fontSize | Default: "0.875rem". | | padding | Default: "0.5rem 1rem". | | borderRadius | Default: "0.25rem". | | opacity | Default: 0.9. | | disableDefaultStyle | When true, the component skips its default inline style string so you can style entirely via CSS (you still need layout/position rules as appropriate). |

Typings only (not read by component.wc.svelte)

The TTooltip interface also lists animation, delay, trigger, customClass, and offset. The current implementation always uses hover + focus on the trigger and a fixed 6px popover offset from Floating UI; those fields are not applied. Prefer documenting behavior above for integration.

Events

| Event | detail | | --- | --- | | visualizationChange | { id: string; show: boolean } |

Emitted when the tooltip opens (show: true) or closes (show: false), including when show is driven by the attribute.

Slots

| Slot | Description | | --- | --- | | (default) | Trigger content in the light DOM. Wrapped for hover/focus tooltip behavior. |

Styling

The floating layer uses position: fixed (Floating UI strategy: "fixed") so it is not clipped by scroll parents such as Bulma .table-container (overflow: auto). Default z-index is 45 via --hb-tooltip-z-index (above --bulma-dropdown-content-z, below --bulma-modal-z; raise on the host if another layer still covers it). The arrow is a small rotated square using the same fill as the bubble.

CSS custom properties

| Variable | Role | | --- | --- | | --hb-tooltip-z-index | Stacking order for the floating bubble (default 45). | | --tooltip-bg | Tooltip surface and arrow fill when set; otherwise the arrow falls back to --bulma-scheme-invert. | | --bulma-scheme-invert | Default arrow/tone fallback when --tooltip-bg is unset. | | --bulma-weight-bold | Font weight for the title line when description is used. | | --bulma-column-gap | Space between title and description blocks. |

CSS parts

None (styleSetup.parts is empty).

Examples

Basic hover tooltip

<hb-tooltip tooltip='{"title":"Help text","placement":"bottom"}'>
  <button type="button">Hover or focus me</button>
</hb-tooltip>

Title and description

<hb-tooltip
  tooltip='{"title":"Volume","description":"Adjusts the output level in percent."}'
>
  <span tabindex="0" class="icon">i</span>
</hb-tooltip>

HTML title (trusted content only)

<hb-tooltip tooltip='{"title":"<strong>Note</strong>: saved automatically.","html":true}'>
  <button type="button">Info</button>
</hb-tooltip>

Programmatic open/close

<hb-tooltip id="tip1" show="yes" tooltip='{"title":"Forced open"}'>
  <span>Trigger</span>
</hb-tooltip>

Listen for visibility if you need to sync UI:

<script>
  document.querySelector("hb-tooltip").addEventListener("visualizationChange", (e) => {
    console.log(e.detail.id, e.detail.show);
  });
</script>

Custom colors via JSON style

<hb-tooltip
  tooltip='{"title":"Styled","style":{"backgroundColor":"#6f42c1","color":"#ffffff","fontSize":"1rem","padding":"0.5rem 1rem","borderRadius":"0.5rem"}}'
>
  <button type="button">Hover</button>
</hb-tooltip>