hb-dialog

Modal dialog built with Bulma’s modal and modal-card patterns inside a shadow root. Visibility is controlled with the string attribute show: "yes" opens the overlay, "no" keeps it unmounted.

While open, the component sets document.body.style.overflow to "hidden" so the page behind the modal does not scroll, and restores the previous value when the dialog closes.

Category: overlays · Tags: overlays, modal
Package: @htmlbricks/hb-dialog · Custom element: <hb-dialog>

Behavior

• Open / close: The modal tree is rendered only when show="yes". Closing sets show to "no" (or removes the open state) depending on the interaction path.
• Transitions: The outer overlay uses a fade transition; the card uses fly (vertical motion). When the enter transition finishes, modalShow fires with show: true; when the exit transition finishes, modalShow fires with show: false.
• Backdrop: With the default backdrop behavior, a click on the dimmed .modal-background (the target that received the click) closes the dialog. To turn that off, set the backdrop property to false in JavaScript (a string attribute such as backdrop="no" is still truthy and will not disable dismissal—see the attributes section below). When backdrop is false, the background layer is still rendered but clicks on it do not dismiss because the handler checks backdrop before closing.
• Keyboard: When keyboard is enabled (default), an Escape listener is attached to document while the modal is open; Escape closes the dialog. When keyboard is disabled, that listener is not registered.
• Header delete control: The small Bulma delete control in the default header only sets show to "no"; it does not dispatch modalConfirm.

Attributes and properties

Names are snake_case. For disable_confirm, hide_close, and hide_confirm, you can use the string values "yes" / "no" (or "true" / "false") and they are normalized inside the component. show uses "yes" / "no" only. For backdrop and keyboard, use real booleans on the element property when you need false (see the note after the table).

| Name | Type | Description | | --- | --- | --- | | id | string (optional) | Identifier echoed on custom events as detail.id. | | show | "yes" | "no" (optional, default "no") | Whether the modal is visible. | | title | string (optional) | Default title when the title slot is not used. | | content | string (optional) | Default body text when the body-content slot is not used. | | closelabel | string (optional) | Default label for the footer close button (slot close-button-label overrides). | | confirmlabel | string (optional) | Default label for the confirm button (slot confirm-button-label overrides). | | backdrop | boolean (optional, default true) | If truthy, a backdrop click can dismiss the modal (when the click target is the background layer). | | keyboard | boolean (optional, default true) | If truthy, Escape closes the modal while it is open. | | describedby | string (optional) | Value for aria-describedby on the dialog root. | | labelledby | string (optional) | Value for aria-labelledby on the dialog root. | | confirm_btn_class | string (optional, default "primary") | Visual style token for the confirm button; mapped to Bulma is-* modifiers (see below). | | close_btn_class | string (optional, default "secondary") | Visual style token for the footer close button; same mapping rules. | | disable_confirm | boolean (optional) | If truthy, the confirm button is disabled. String "yes" / "true" is coerced to a disabled button. | | hide_close | boolean (optional) | If truthy, hides the header delete control and the footer close button. Coerced from "yes" / "true". | | hide_confirm | boolean (optional) | If truthy, hides the confirm button. Coerced from "yes" / "true". | | style | string (optional) | Declared in typings; the Svelte implementation does not currently destructure or forward this as a component prop. |

For backdrop and keyboard, the implementation uses ordinary JavaScript truthiness (unlike disable_confirm / hide_close / hide_confirm, which normalize "yes" / "true"). A string attribute like keyboard="no" is still truthy in JS. For a reliable “off”, set the property to false in JavaScript (or omit the attribute and use defaults as appropriate).

Button style tokens (confirm_btn_class / close_btn_class)

Values are compared case-insensitively, optional btn- prefix is stripped, then mapped to Bulma modifiers:

| Token | Bulma modifier | | --- | --- | | primary | is-primary | | secondary | is-light | | success | is-success | | danger | is-danger | | warning | is-warning | | info | is-info | | light | is-light | | dark | is-dark | | link | is-ghost | | (unknown) | is-light |

Slots

| Slot | Purpose | | --- | --- | | header | Replaces the entire modal head (title row and optional delete control). The default head includes the title slot and the delete button when hide_close is not set. | | title | Heading inside the default header when header is not overridden. | | body-content | Main body; falls back to the content prop (or a short default string). | | modal-footer | Wraps the footer region; default content wraps the footer slot. | | footer | Default footer: a .buttons group with close and confirm actions (respecting hide_close / hide_confirm). | | close-button-label | Inner text of the default footer close button (defaults to closelabel or "Close"). | | confirm-button-label | Inner text of the default confirm button (defaults to confirmlabel or "Save changes"). |

Custom events

Listen with addEventListener or framework bindings on the host element.

| Event | detail | When it fires | | --- | --- | --- | | modalShow | { id: string; show: boolean } | After the overlay enter transition ends (show: true) or after the leave transition ends (show: false). | | modalConfirm | { id: string; confirm: boolean } | confirm: true when the user activates the confirm button (then the dialog closes). confirm: false when the user activates the default footer close button (then the dialog closes). Not emitted for header delete, backdrop dismiss, or Escape. |

Styling: CSS custom properties

These are documented for :host (Bulma modal layout tokens; see Bulma CSS variables).

| Variable | Role | | --- | --- | | --hb-modal-max-width | Maximum width of the modal card (.modal-card). Default 40rem. | | --bulma-modal-card-head-padding | Padding for .modal-card-head. Default 1rem 1.25rem. | | --bulma-modal-card-body-padding | Padding for .modal-card-body. Default 1rem 1.25rem. | | --bulma-modal-card-title-size | Title font size. Default var(--bulma-size-5). | | --bulma-modal-card-title-line-height | Title line height. Default 1.25. | | --bulma-modal-card-spacing | Spacing between card regions. Default 1.5rem. |

Additional --bulma-* variables from Bulma’s setup may apply on :host depending on your theme.

CSS parts

| Part | Target | Use | | --- | --- | --- | | modal-dialog | .modal-card | Size, border radius, shadows, or layout of the dialog surface. |

HTML example

<hb-dialog
  id="confirm-delete"
  show="yes"
  title="Delete item?"
  content="This cannot be undone."
  confirmlabel="Delete"
  closelabel="Cancel"
></hb-dialog>

const el = document.querySelector("hb-dialog");
el.addEventListener("modalConfirm", (e) => {
  if (e.detail.confirm) {
    // user chose Delete
  } else {
    // user chose Cancel
  }
});
el.addEventListener("modalShow", (e) => {
  console.log("dialog visibility:", e.detail.show);
});

To open or close from script, set the reflected property or attribute, for example el.setAttribute("show", "yes") / el.setAttribute("show", "no").

Accessibility notes

• The root node uses role="dialog", aria-modal="true", and optional aria-labelledby / aria-describedby when you pass labelledby and describedby (typically IDs of elements in the light DOM).
• Focus management is not fully delegated outside the shadow tree; validate focus order and screen reader behavior in your host page when using slots or dynamic content.

Internationalization

No built-in i18n language list is shipped for this component; use props and slots for copy.