LanternUI.Components.Modal (LanternUI v0.9.0)

Copy Markdown View Source

Modal dialog on the shared overlay runtime (focus trap, Escape/outside dismissal, prefers-reduced-motion-aware fade).

<.modal id="confirm-delete">
  <h2>Delete 3 objects?</h2>
  <p>This cannot be undone.</p>
  <.button phx-click={LanternUI.close_dialog("confirm-delete")}>Cancel</.button>
  <.button variant="solid" color="danger" phx-click="delete">Delete</.button>
</.modal>

<.button phx-click={LanternUI.open_dialog("confirm-delete")}>Delete…</.button>

The API mirrors Fluxon's modal/1; open/close from the client with LanternUI.open_dialog/1 / close_dialog/1 (JS commands) or from the server with LanternUI.open_dialog(socket, id) / close_dialog(socket, id). Animation-tuning attrs (animation*) are accepted for Fluxon compatibility; the fade duration comes from the --lantern-duration token.

The dialog is Zag-driven (a @zag-js/dialog state machine, loaded on demand): the hook root carries data-zag plus data-scope="dialog" / data-part anatomy, and Zag owns open state, focus trap + return, scroll lock, Escape/outside dismissal, and initial focus. Styling stays lui-* tokens. The server owns open via data-open (a patch asserting it re-opens, withdrawing it closes); controlled makes the server value strict truth with on_change fan-out.

Hand-rolled LanternModal roots without data-zag keep the legacy hook behavior, so existing open_dialog/close_dialog call sites keep working; new markup should use this component.

Summary

Functions

modal(assigns)

Functions

modal(assigns)

Attributes

  • id (:string) (required) - Stable DOM id used by open_dialog/close_dialog.
  • open (:boolean) - render already open (server-driven modals). Defaults to false.
  • on_open (Phoenix.LiveView.JS) - JS command run when the modal opens. Defaults to nil.
  • on_close (Phoenix.LiveView.JS) - JS command run when the modal closes. Defaults to nil.
  • class (:any) - Extra classes on the dialog panel. Defaults to nil.
  • container_class (:any) - Extra classes on the overlay root. Defaults to nil.
  • backdrop_class (:any) - Extra classes on the dimmed backdrop. Defaults to nil.
  • close_on_esc (:boolean) - Close when Escape is pressed. Defaults to true.
  • close_on_outside_click (:boolean) - Close when the backdrop is clicked. Defaults to true.
  • prevent_closing (:boolean) - Block Escape and outside-click close. Defaults to false.
  • hide_close_button (:boolean) - Hide the built-in close control. Defaults to false.
  • role (:string) - ARIA role for the dialog panel. Defaults to "dialog".
  • aria_label (:string) - Accessible name for the dialog panel. Defaults to nil.
  • aria_labelledby (:string) - Id of the dialog title element. Defaults to nil.
  • aria_describedby (:string) - Id of the dialog description element. Defaults to nil.
  • initial_focus (:string) - Selector for the element or region that receives focus when opened. Defaults to nil.
  • placement (:string) - Vertical panel placement within the viewport. Defaults to "center". Must be one of "center", or "top".
  • animation (:string) - accepted for Fluxon compat; fade is token-driven. Defaults to nil.
  • animation_enter (:string) - accepted for Fluxon compat. Defaults to nil.
  • animation_leave (:string) - accepted for Fluxon compat. Defaults to nil.
  • controlled (:boolean) - Strict server-driven open state: open is truth, patches flow into the machine. Defaults to false.
  • on_change (:string) - Server event pushed on open change (lantern:dialog:open/close replies). Defaults to nil.
  • on_change_client (:string) - Bubbling DOM CustomEvent dispatched on open change. Defaults to nil.
  • Global attributes are accepted. Arbitrary HTML/phx-* attributes passed through.

Slots

  • inner_block (required) - Dialog body content.