hb-toast — integrator guide

Category: overlays · Tags: overlays, notifications · Package: @htmlbricks/hb-toast · Custom element: hb-toast

Summary

hb-toast is a Bulma-styled floating notification: a dismissible card with optional status chip, body copy, optional action buttons, and an optional bottom progress bar. It is positioned in a corner or edge of the viewport (configurable), uses Bootstrap Icons for built-in status icons, and communicates with the host through changeVisibility and action custom events.

Use it for transient messages, timed auto-dismiss, upload or task progress, or confirm / cancel flows without a full modal.

Props and attributes

Attributes use snake_case. In HTML, values are strings only: use yes / no for visibility, numbers as strings (for example timeout="5000"), and buttons as a JSON array string. From JavaScript you may assign properties with richer types where your bindings support it (for example a parsed buttons array).

| Attribute | Required | Description | |-----------|----------|-------------| | show | Yes | yes shows the toast; no hides it and clears timers. | | title | Yes | Bold header line (also mirrored if the header_strong slot is empty). | | content | Yes | Main message HTML is not assumed; plain text is shown in the default body (slot body overrides). | | img | Yes (per typings) | String (URL or data URI). Present on the public Component type and catalog examples; the current implementation does not render this value in the shadow tree. Use the header_icon slot for a custom image or icon. | | id | No | Included in event detail for correlation when multiple toasts exist. | | style | No | On the TypeScript interface for host-level styling; not forwarded into inner markup in the current source. | | small | No | Fixed status chip text. When set, it overrides automatic status (countdown, progress label, or elapsed time). | | level | No | Semantic tone: primary, secondary (link hue), success, danger, warning, info, light, dark. Default info. Sets --hb-toast-accent as hsl(var(--bulma-*-h), …) (Bulma has no single var(--bulma-primary) paint) for start border, icon/status tint, and progress fill; card uses --bulma-background / --bulma-text. | | position | No | top-left, top-center, top-right, bottom-left, bottom-center, bottom-right. Default bottom-right. | | timeout | No | Auto-dismiss delay in milliseconds (coerced with Number). When set and greater than zero, and progress is not a valid 0–100 value, the toast closes when the timer elapses and the bar animates from 0% to 100% over that interval. | | progress | No | String parsed as a number 0–100. When valid, drives the bar width and status text (percentage) unless small is set. When the value reaches 100% while visible, the toast auto-closes after its fade-out (same path as timeout completion). | | buttons | No | JSON string (or array from JS) of TToastButton objects: type confirm | cancel; optional action, text, icon (Bootstrap Icons class, e.g. bi-check-lg), themeColor, color (inline background on the button). Defaults supply label, theme, and icon per type. |

Button objects (buttons)

Each entry is merged with defaults:

• confirm: default text “Confirm”, theme success, icon bi-check-lg.
• cancel: default text “Cancel”, theme secondary (rendered as Bulma is-light for secondary), icon bi-x-lg.

Clicking a button dispatches action with the button’s action string, then closes the toast.

Runtime behavior

• Visibility: With show="yes", the toast enters with a short fade-in. With show="no", timers and intervals are cleared.
• Close control: The corner delete control calls close: timers stop, show becomes no, and changeVisibility fires with show: false (no disappear flag).
• Timed dismiss: If timeout is a positive number and there is no external numeric progress, a single timer runs for that many milliseconds, the progress bar fills over the same period, then autoClose runs: after the fade-out buffer, changeVisibility fires with show: false and disappear: true.
• Status chip: If small is a non-empty string, it is always shown as the chip text. Otherwise: if progress parses to a number, the chip shows {percentage}%; if timeout is positive, the chip shows a human-readable remaining countdown (for example “2 minutes 30 seconds remaining”); if neither applies, the chip shows elapsed time since open (“now”, then “1 second ago”, and so on). An explicit empty small suppresses that computed line unless you fill header_small.
• Progress bar: Shown when progress is a valid percentage or when timeout is positive (timeout mode). External progress clamps to 0–100; invalid or empty progress falls back to timeout-driven animation only.
• Icons in the chip: Context icons are bi-tag (custom small), bi-reception-4 (percentage), bi-hourglass-split (countdown), bi-clock-history (elapsed).

Events

| Event | detail | |-------|----------| | changeVisibility | { id: string; show: boolean; disappear?: boolean } — fired when the toast is hidden programmatically, by the user, or after auto-dismiss. disappear: true is set on auto close after timeout or when progress reaches 100%. | | action | { id: string; action?: string } — fired when an action button is pressed; action matches the action field on the clicked TToastButton. |

Example (vanilla JS)

const toast = document.querySelector("hb-toast");

toast.addEventListener("changeVisibility", (e) => {
  console.log(e.detail); // { id, show, disappear? }
});

toast.addEventListener("action", (e) => {
  console.log(e.detail); // { id, action? }
});

Styling (Bulma)

Shadow styles forward Bulma 1.x from styles/bulma.scss. Theme the host from the light DOM with --bulma-* variables (see Bulma CSS variables).

Documented styleSetup variables (extra/docs.ts):

| Variable | Type | Role | |----------|------|------| | --bulma-column-gap | number | Edge insets and internal gaps in the toast shell. | | --bulma-radius | number | Corner radius of the floating panel. | | --bulma-border-weak | color | Hairline border and dividers. | | --bulma-shadow | string | Drop shadow for the panel. | | --bulma-text | color | Secondary and meta text. | | --bulma-text-strong | color | Title and strong header tone. | | --bulma-block-spacing | number | Vertical rhythm in header and footer stacks. |

CSS ::part

| Part | Description | |------|-------------| | toast | Outer card: theme background + text; level drives --hb-toast-accent (border, progress, icons). | | status | Status row under the title: countdown, progress percentage, small text, or slot-driven content. |

Slots

| Slot | Description | |------|-------------| | header_icon | Leading icon area; default is a Bootstrap Icons bell (bi-bell). | | header_strong | Optional content before the title text in the title line (slot is empty by default; title still renders). | | header_small | Overrides the default status chip text (same surface as automatic timeout / progress / elapsed). | | body | Main copy; default content is content. |

Examples

Basic open toast

<hb-toast
  show="yes"
  title="Notice"
  content="Hello, world! This is a toast message."
  img=""
  level="info"
></hb-toast>

Timed auto-dismiss (5 seconds)

<hb-toast
  show="yes"
  title="Saved"
  content="Your changes were stored."
  img=""
  timeout="5000"
  level="success"
></hb-toast>

Fixed progress (string 0–100)

<hb-toast
  show="yes"
  title="Upload"
  content="Uploading your file…"
  img=""
  progress="42"
  level="warning"
></hb-toast>

Confirm / cancel (buttons as JSON)

<hb-toast
  id="confirm-1"
  show="yes"
  title="Confirm"
  content="Proceed with this action?"
  img=""
  level="light"
  buttons='[{"type":"cancel","action":"dismiss"},{"type":"confirm","action":"proceed","text":"Yes","icon":"bi-check-circle"}]'
></hb-toast>

Custom leading icon (slot)

<hb-toast show="yes" title="Alert" content="Something happened." img="" level="danger">
  <span slot="header_icon" class="icon is-medium">
    <i class="bi bi-exclamation-triangle" aria-hidden="true"></i>
  </span>
</hb-toast>