This component is meant for situations where critical information must be conveyed, and an explicit response is required from the user. It is typically used for confirmation dialogs, warning messages, error notifications, and other scenarios where an immediate decision is necessary.

For non-critical dialogs, such as those containing forms or additional information, use Doggo.Components.build_modal/1 instead.

Maturity: Developing

Usage

<.alert_dialog id="end-session-modal">
  <:title>End Training Session Early?</:title>
  <p>
    Are you sure you want to end the current training session with Bella?
    She's making great progress today!
  </p>
  <:footer>
    <.button phx-click="end-session">
      Yes, end session
    </.button>
    <.button phx-click={Doggo.JS.hide_modal("end-session-modal")}>
      No, continue training
    </.button>
  </:footer>
</.alert_dialog>

To open the dialog, use the Doggo.JS.show_modal/1 function.

<.button
  phx-click={Doggo.JS.show_modal("end-session-modal")}
  aria-haspopup="dialog"
>
  show
</.button>

With HTML attributes

command and commandfor are the Invoker Commands API. Unlike the other two ways, this API needs no JavaScript at all.

<.button command="show-modal" commandfor="end-session-modal">show</.button>

Both attributes are recent, so the hook handles them if the browser doesn't support them.

Closing

The alert dialog can be closed by:

• using Doggo.JS.hide_modal/1,
• using the close button or Esc, unless closedby is "none", or
• clicking outside it, if closedby is "any".

Each of them runs on_cancel once.

Semantics

The dialog is opened with showModal(), so the browser puts it in the top layer, draws ::backdrop, makes the rest of the document inert and keeps the focus inside. aria-modal is not rendered, because showModal() already marks the component as a modal.

Focus

showModal() moves the focus into the dialog to the first element with the autofocus attribute, or the first focusable element if no element has it.

An alert dialog renders no close button by default, so the first focusable element is usually the first control in the :footer slot. With a close button, it is the close button. Neither is likely to be the right element to focus.

Set autofocus on the element that should receive the focus:

<:footer>
  <.button phx-click="end-session">Yes, end session</.button>
  <.button
    autofocus
    phx-click={Doggo.JS.hide_modal("end-session-modal")}
  >
    No, continue training
  </.button>
</:footer>

In an alert dialog, the focus should move to the least destructive action, as recommended in the ARIA Authoring Practices.

CSS

A dialog is hidden until it is opened, so no rule is needed for that. Style the backdrop with dialog.alert-dialog::backdrop.

Caveats

An alert dialog defaults to closedby="none", which means that it does not render a close button. Provide your own control in the :footer slot.

Keyboard

• Esc - close the dialog, unless closedby is "none".