Dialog is a floating surface used to display transient content such as confirmation actions, selection options, and more.

A dialog is created with box/1 slots.

<.dialog>
  <:header_title>Title</:header_title>
  <:body>
    Message in a dialog
  </:body>
</.dialog>

Opening and closing the dialog

Invoking open and close

Functions open_dialog/1 and close_dialog/1 can be called with phx-click, passing the dialog's id (the alternative approach is to conditionally render - see below).

<.button phx-click={open_dialog("my-dialog")}>Open</.button>

<.dialog id="my-dialog">
  <:body>
    Message in a dialog
    <.button phx-click={close_dialog("my-dialog")}>Close</.button>
  </:body>
</.dialog>

Clicking the backdrop will automatically invoke cancel_dialog.

Pressing Escape will close the open dialog (unless is_escapable is explicitly set to false). In case of stacked dialogs, the included Prompt hook ensures that only the top dialog will be closed.

Routes and other conditionals

To show the dialog at a specific route (or with any other condition), use Phoenix's :if attribute, combined with is_show. The on_cancel attribute can then be used to redirect to the originating route:

<.dialog
  id="new-post-dialog"
  :if={@live_action == :create}
  is_show
  on_cancel={JS.patch(~p"/posts")}
>
  <:body>
    Post form
  </:body>
</.dialog>

To display the dialog on page load without a fade-in transition, add attribute is_show_on_mount. See PrimerLive.StatefulConditionComponent for an example.

Other attributes

Add a backdrop. Optionally add backdrop_strength with value "strong" or "light":

<.dialog is_backdrop backdrop_strength="light">
  ...
</.dialog>

Create a modal dialog; clicking the backdrop (if used) or outside of the dialog will not close the dialog:

<.dialog is_modal>
  ...
</.dialog>

Create faster fade in and out:

<.dialog is_fast>
  ...
</.dialog>

A narrow dialog:

<.dialog is_narrow>
  ...
</.dialog>

A wide dialog:

<.dialog is_wide>
  ...
</.dialog>

The dialog will focus the first element after opening. Pass focus_after_opening_selector with a selector to give focus to a different element.

<.dialog focus_after_opening_selector="#login_first_name">
  ...
</.dialog>

After closing the dialog, return the focus to the originating element. Improve accessibility by implementing this ARIA Dialog Pattern.

<.button id="opens-dialog" phx-click={open_dialog("my-dialog")}>Open</.button>

<.dialog id="my-dialog" focus_after_closing_selector="#opens-dialog">
  ...
</.dialog>

Long content will automatically show a scrollbar. To change the maxium height of the dialog, use a CSS value. Use unit vh or %.

<.dialog max_height="50vh">
  ...
</.dialog>

Add a header title and a footer.

box slot header slot is automatically added when header_title is used.

<.dialog>
  <:header_title>Title</:header_title>
  ...
  <:footer>Footer</:footer>
</.dialog>

A dialog with rows:

 <.dialog>
  <:header_title>Title</:header_title>
  <:row>Row 1</:row>
  <:row>Row 2</:row>
  <:row>Row 3</:row>
  <:row>Row 4</:row>
  <:footer>Footer</:footer>
</.dialog>

Dialog content is automatically wrapped inside a Phoenix.Component.focus_wrap/1 so that navigating with Tab won't leave the dialog.

<.dialog is_backdrop is_modal>
  <:header_title>Title</:header_title>
  <:body>
  <.text_input form={:user} field={:first_name} is_form_control />
  <.text_input form={:user} field={:last_name} is_form_control />
  </:body>
</.dialog>

Attributes

• focus_after_closing_selector (:string) - Returns focus to the specified element after closing the dialog. Pass the element selector. Improve accessibility by implementing this ARIA Dialog Pattern.

  Defaults to nil.

• focus_after_opening_selector (:string) - By default, the first interactive element gets focus after opening the dialog. Use to set focus to a different element after opening. Pass the element selector.

  Defaults to nil.

• id (:string) (required) - Dialog element id, used for opening and closing from the outside.

• is_backdrop (:boolean) - Generates a backdrop background with a default strength and tint values.

  Default backdrop strenght:

  • dialog and drawer: "medium"
  • menus: "light"

  Default tint: "dark".

  Defaults to false.

• backdrop_strength (:string) - Backdrop strenght. Overrides the default value from is_backdrop. Defaults to nil.

• backdrop_tint (:string) - Backdrop tint. Overrides the default value from is_backdrop. Defaults to nil.

• is_escapable (:boolean) - Closes the content when the Escape key is pressed. Set to false to prevent this. Defaults to true.

• is_fast (:boolean) - Generates fast fade transitions for backdrop and content. Defaults to false.

• is_modal (:boolean) - Sets modal behavior: the dialog can only be closed with Escape or by clicking a close button. Defaults to false.

• is_show (:boolean) - Sets the display state of the dialog. Control conditional display by using Phoenix's :if attribute.

  Example:

  <dialog is_show :if={@live_action in [:new, :edit]}>
    ...
  </dialog>

  Defaults to false.

• show_state (:string) - Use when the dialog is already displayed, and should be persisted when navigating to another LiveViews (for example to hide the dialog with a transition after having navigated to a new route). This method does require that the dialog is available on the other LiveView page, so it is best suited for "global" components such as navigation panels and app header menus.

  Use together with is_show.

  Values:

  • "default": No change.
  • "onset": Preparation for the "hold" state. Removes the "phx-remove" attribute so that navigating away doesn't cause a close transition.
  • "hold": Removes the "phx-remove" attribute as well as opening transitions and first focus.

  Defaults to "default".

• is_show_on_mount (:boolean) - Displays the dialog on mount without fade-in transition. Control conditional display by using Phoenix's :if attribute.

  Example:

  <dialog is_show is_show_on_mount :if={@live_action in [:new, :edit]}>
    ...
  </dialog>

  Defaults to false.

• on_cancel (Phoenix.LiveView.JS) - Phoenix.LiveView.JS command to configure the closing/cancel event of the dialog, for example: on_cancel={JS.navigate(~p"/posts")}. Defaults to nil.

• status_callback_selector (:string) - Receiver to get status callback events. Events are passed from the Prompt hook using pushEventTo. Pass the HTML selector of the receiver of the LiveComponent or LiveView the element is defined in.

  The event sends the object named "primer_live:prompt" with payload:

  %{
    "selector" => "",  # callback selector
    "elementId" => "", # the dialog id
    "status" => ""     # possible values: "opening", "opened", "closing", "closed"
  }

  Defaults to nil.

• transition_duration (:integer) - The number of milliseconds to fade-in/out the dialog. Adds a CSS style attribute to the dialog HTML. Defaults to 170.

• class (:any) - Additional classname. Defaults to nil.

• classes (:map) - Additional classnames for dialog elements.

  Any provided value will be appended to the default classname.

  Default map:

  %{
    # Dialog classes
    dialog_wrapper: "",  # The outer element
    dialog: "",          # Dialog element
    # Box classes - see box component:
    box: "",
    header: "",
    row: "",
    body: "",
    footer: "",
    header_title: "",
    link: "",
  }

  Defaults to %{link: nil, header: nil, body: nil, box: nil, dialog: nil, row: nil, footer: nil, header_title: nil, dialog_wrapper: nil}.

• is_narrow (:boolean) - Generates a smaller dialog, width: 320px (default: 440px). Defaults to false.

• is_wide (:boolean) - Generates a wider dialog, width: 640px (default: 440px). Defaults to false.

• max_height (:string) - Maximum height of the dialog as CSS value. Use unit vh or %. Defaults to "80vh".

• max_width (:string) - Maximum width of the dialog as CSS value. Use unit vh or %. Defaults to "90vw".

• Global attributes are accepted.

Slots

• header_title - Dialog header title. Uses box/1 header_title slot.Note that slot header is automatically created to ensure the correct close button.Accepts attributes:
  • class (:any) - Additional classname.
  • id (:any) - Component DOM id.
  • style (:string) - Additional CSS styles.
  • aria-disabled (:string) - ARIA disabled attribute.
  • aria-expanded (:string) - ARIA disabled attribute.
  • aria-hidden (:string) - ARIA hiddeh attribute.
  • aria-label (:string) - ARIA label attribute.
  • aria-labelledby (:string) - ARIA labelledby attribute.
  • aria-required (:string) - ARIA disabled attribute.
  • aria-role (:string) - ARIA role attribute.
  • rest (:any)
• body - Dialog body. Uses box/1 body slot. Accepts attributes:
  • class (:any) - Additional classname.
  • id (:any) - Component DOM id.
  • style (:string) - Additional CSS styles.
  • aria-disabled (:string) - ARIA disabled attribute.
  • aria-expanded (:string) - ARIA disabled attribute.
  • aria-hidden (:string) - ARIA hiddeh attribute.
  • aria-label (:string) - ARIA label attribute.
  • aria-labelledby (:string) - ARIA labelledby attribute.
  • aria-required (:string) - ARIA disabled attribute.
  • aria-role (:string) - ARIA role attribute.
  • rest (:any)
• row - Dialog row. Uses box/1 row slot. Accepts attributes:

  • href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other slot attributes to the link.

  • patch (:string) - Link attribute - see href.

  • navigate (:string) - Link attribute - see href.

  • phx-click (:string)

  • phx-target (:any)

  • phx-value-item (:any) - The payload parameter for the selected value to be sent with an event.

    Examples:

    <:row
      phx-click="select_row"
      phx-value-item={row_id}
    >
      ...
    
    def handle_event(
      "select_row", %{"item" => row_id}, socket) do
      ...

  • class (:any) - Additional classname.

  • id (:any) - Component DOM id.

  • style (:string) - Additional CSS styles.

  • aria-disabled (:string) - ARIA disabled attribute.

  • aria-expanded (:string) - ARIA disabled attribute.

  • aria-hidden (:string) - ARIA hiddeh attribute.

  • aria-label (:string) - ARIA label attribute.

  • aria-labelledby (:string) - ARIA labelledby attribute.

  • aria-required (:string) - ARIA disabled attribute.

  • aria-role (:string) - ARIA role attribute.

  • rest (:any)

• footer - Dialog footer. Uses box/1 footer slot. Accepts attributes:
  • class (:any) - Additional classname.
  • id (:any) - Component DOM id.
  • style (:string) - Additional CSS styles.
  • aria-disabled (:string) - ARIA disabled attribute.
  • aria-expanded (:string) - ARIA disabled attribute.
  • aria-hidden (:string) - ARIA hiddeh attribute.
  • aria-label (:string) - ARIA label attribute.
  • aria-labelledby (:string) - ARIA labelledby attribute.
  • aria-required (:string) - ARIA disabled attribute.
  • aria-role (:string) - ARIA role attribute.
  • rest (:any)
• inner_block - Unstructured dialog content. Uses box/1 inner_block slot.

Reference

Primer Dialog