12 · Overlays

Modal

animation fade · scale · sheet · shift-down · shift-up · size xs–full · placement top/center/bottom · origin · close_variant · alertdialog

A modal dialog for short tasks and confirmations.

animation (the backdrop always fades)

fade
scale
sheet
shift-down
shift-up
scale · origin=top
.heex
<div class="grid grid-cols-3 gap-3">
  <div :for={{{a, pl, label, o}, i} <- Enum.with_index([{"fade", "center", "fade", "center"}, {"scale", "center", "scale", "center"}, {"sheet", "bottom", "sheet", "center"}, {"shift-down", "center", "shift-down", "center"}, {"shift-up", "center", "shift-up", "center"}, {"scale", "center", "scale · origin=top", "top"}])} class="relative overflow-hidden rounded-[14px] bg-page shadow-[inset_0_0_0_1px_var(--lu-line)] h-[230px] [&>[data-part=modal-overlay]]:absolute [&>[data-part=modal-overlay]]:inset-0 [&>[data-part=modal-overlay]]:rounded-none [&>[data-part=modal-overlay]]:p-3.5">
    <div class="absolute inset-0 flex flex-col gap-2.5 px-[18px] py-4"><.skeleton animation={nil} class="h-[9px] w-[38%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[70%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[55%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[62%] rounded-[5px]" /></div>
    <.modal inline id={"mo-anim-#{i}"} animation={a} placement={pl} origin={o} size="xs" title="Exportar relatório" close_button={false}>
      <.skeleton animation={nil} class="h-[7px] w-[90%] rounded-sm" /><.skeleton animation={nil} class="h-[7px] w-[70%] rounded-sm" />
      <:footer><.button color="neutral" variant="soft" size="xs">Cancelar</.button><.button color="neutral" size="xs">Salvar</.button></:footer>
    </.modal>
    <span class="absolute bottom-2 left-2.5 z-50 font-mono text-[11px] text-muted">{label}</span>
  </div>
</div>

size (max width)

xs
320px
sm
440px
md
560px
lg
720px (padrão)
xl
960px
full
tela inteira
.heex
<div class="flex flex-col gap-2">
  <div :for={{s, w, px} <- [{"xs", "w-40", "320px"}, {"sm", "w-[220px]", "440px"}, {"md", "w-[280px]", "560px"}, {"lg", "w-[360px]", "720px (padrão)"}, {"xl", "w-[460px]", "960px"}, {"full", "w-[620px]", "tela inteira"}]} class="flex flex-wrap items-center gap-2.5">
    <span class="w-10 font-mono text-xs text-muted">{s}</span>
    <div class={["flex h-[22px] max-w-full items-center rounded-md bg-sunken px-2 font-mono text-xs text-muted shadow-[inset_0_0_0_1px_var(--lu-line)]", w]}>{px}</div>
  </div>
</div>

placement · close_variant · role

placement=top
center
bottom
close_variant=chip

Excluir pedido #2488?

role=alertdialog
.heex
<div class="grid grid-cols-3 gap-3">
  <div :for={{pl, label} <- [{"top", "placement=top"}, {"center", "center"}, {"bottom", "bottom"}]} class="relative overflow-hidden rounded-[14px] bg-page shadow-[inset_0_0_0_1px_var(--lu-line)] h-[230px] [&>[data-part=modal-overlay]]:absolute [&>[data-part=modal-overlay]]:inset-0 [&>[data-part=modal-overlay]]:rounded-none [&>[data-part=modal-overlay]]:p-3.5">
    <div class="absolute inset-0 flex flex-col gap-2.5 px-[18px] py-4"><.skeleton animation={nil} class="h-[9px] w-[38%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[70%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[55%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[62%] rounded-[5px]" /></div>
    <.modal inline id={"mo-place-#{pl}"} placement={pl} size="xs" title="Exportar relatório" close_button={false}>
      <.skeleton animation={nil} class="h-[7px] w-[90%] rounded-sm" /><.skeleton animation={nil} class="h-[7px] w-[70%] rounded-sm" />
      <:footer><.button color="neutral" variant="soft" size="xs">Cancelar</.button><.button color="neutral" size="xs">Salvar</.button></:footer>
    </.modal>
    <span class="absolute bottom-2 left-2.5 z-50 font-mono text-[11px] text-muted">{label}</span>
  </div>
  <div class="relative overflow-hidden rounded-[14px] bg-page shadow-[inset_0_0_0_1px_var(--lu-line)] h-[230px] [&>[data-part=modal-overlay]]:absolute [&>[data-part=modal-overlay]]:inset-0 [&>[data-part=modal-overlay]]:rounded-none [&>[data-part=modal-overlay]]:p-3.5">
    <div class="absolute inset-0 flex flex-col gap-2.5 px-[18px] py-4"><.skeleton animation={nil} class="h-[9px] w-[38%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[70%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[55%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[62%] rounded-[5px]" /></div>
    <.modal inline id="mo-chip" size="xs" close_variant="chip" class="p-0">
      <div class="h-[110px] bg-[linear-gradient(135deg,var(--lu-accent-300),var(--lu-accent-700))]"></div>
      <div class="p-2.5"><b>Capa da loja</b></div>
    </.modal>
    <span class="absolute bottom-2 left-2.5 z-50 font-mono text-[11px] text-muted">close_variant=chip</span>
  </div>
  <div class="relative overflow-hidden rounded-[14px] bg-page shadow-[inset_0_0_0_1px_var(--lu-line)] h-[230px] [&>[data-part=modal-overlay]]:absolute [&>[data-part=modal-overlay]]:inset-0 [&>[data-part=modal-overlay]]:rounded-none [&>[data-part=modal-overlay]]:p-3.5">
    <div class="absolute inset-0 flex flex-col gap-2.5 px-[18px] py-4"><.skeleton animation={nil} class="h-[9px] w-[38%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[70%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[55%] rounded-[5px]" /><.skeleton animation={nil} class="h-[9px] w-[62%] rounded-[5px]" /></div>
    <.modal inline id="mo-alert" size="xs" role="alertdialog" title="Excluir pedido #2488?" close_button={false}>
      <.skeleton animation={nil} class="h-[7px] w-[85%] rounded-sm" />
      <:footer><.button color="neutral" variant="soft" size="xs">Cancelar</.button><.button color="error" size="xs">Excluir</.button></:footer>
    </.modal>
    <span class="absolute bottom-2 left-2.5 z-50 font-mono text-[11px] text-muted">role=alertdialog</span>
  </div>
</div>

API values that complete the parity

close_variant=plain
role="dialog"role=dialog
.heex
<div class="grid grid-cols-3 gap-3.5">
  <div class="flex flex-col items-start gap-1.5">
    <div class="relative h-[110px] w-[260px] [&>[data-part=modal-overlay]]:absolute [&>[data-part=modal-overlay]]:inset-0 [&>[data-part=modal-overlay]]:rounded-none [&>[data-part=modal-overlay]]:p-3.5"><.modal inline id="mo-plain" size="xs" close_variant="plain" title="Título">
      <.skeleton animation={nil} class="h-[7px] w-4/5 rounded-sm" />
    </.modal></div>
    <span class="font-mono text-[11px] text-muted">close_variant=plain</span>
  </div>
  <div class="flex flex-col items-start gap-1.5"><.badge color="neutral" variant="soft">role="dialog"</.badge><span class="font-mono text-[11px] text-muted">role=dialog</span></div>
</div>

Try it: opens the real modal (animation, size, placement)

animation
size
outros
.heex
<div class="flex flex-col gap-3">
  <div class="flex flex-wrap items-center gap-2.5">
    <span class="w-20 font-mono text-xs text-muted">animation</span>
    <.button :for={a <- ~w(fade scale sheet shift-down shift-up)} color="neutral" variant="outline" size="sm" aria-haspopup="dialog" aria-controls={"mo-live-a-#{a}"} phx-click={LedgerUI.open("mo-live-a-#{a}")}>{a}</.button>
  </div>
  <div class="flex flex-wrap items-center gap-2.5">
    <span class="w-20 font-mono text-xs text-muted">size</span>
    <.button :for={s <- ~w(xs sm md lg xl full)} color="neutral" variant="soft" size="sm" aria-haspopup="dialog" aria-controls={"mo-live-s-#{s}"} phx-click={LedgerUI.open("mo-live-s-#{s}")}>{s}</.button>
  </div>
  <div class="flex flex-wrap items-center gap-2.5">
    <span class="w-20 font-mono text-xs text-muted">outros</span>
    <.button color="neutral" variant="outline" size="sm" aria-haspopup="dialog" aria-controls="mo-live-top" phx-click={LedgerUI.open("mo-live-top")}>placement=top</.button>
    <.button color="neutral" variant="outline" size="sm" aria-haspopup="dialog" aria-controls="mo-live-bottom" phx-click={LedgerUI.open("mo-live-bottom")}>placement=bottom</.button>
    <.button color="error" variant="soft" size="sm" aria-haspopup="dialog" aria-controls="mo-live-alert" phx-click={LedgerUI.open("mo-live-alert")}>Confirmar exclusão</.button>
    <.button color="neutral" variant="outline" size="sm" aria-haspopup="dialog" aria-controls="mo-live-chip" phx-click={LedgerUI.open("mo-live-chip")}>close_variant=chip</.button>
  </div>

  <.modal :for={a <- ~w(fade scale sheet shift-down shift-up)} id={"mo-live-a-#{a}"} animation={a} size="sm" title="Exportar relatório" description={"animation=#{a}"}>
    <p class="m-0 text-[14px] text-muted">Escolha o formato do arquivo. Feche pelo ×, pelo Esc ou clicando no fundo.</p>
    <:footer>
      <.button color="neutral" variant="soft" size="sm" phx-click={LedgerUI.close("mo-live-a-#{a}")}>Cancelar</.button>
      <.button color="neutral" size="sm" phx-click={LedgerUI.close("mo-live-a-#{a}")}>Exportar</.button>
    </:footer>
  </.modal>
  <.modal :for={s <- ~w(xs sm md lg xl full)} id={"mo-live-s-#{s}"} animation="scale" size={s} title={"size=#{s}"} description="Largura máxima do modal">
    <p class="m-0 text-[14px] text-muted">Conteúdo do modal.</p>
    <:footer>
      <.button color="neutral" variant="soft" size="sm" phx-click={LedgerUI.close("mo-live-s-#{s}")}>Fechar</.button>
    </:footer>
  </.modal>
  <.modal id="mo-live-top" placement="top" animation="shift-down" size="md" title="placement=top" description="Abre perto do topo.">
    <p class="m-0 text-[14px] text-muted">O modal fica rente ao topo da janela.</p>
    <:footer>
      <.button color="neutral" variant="soft" size="sm" phx-click={LedgerUI.close("mo-live-top")}>Fechar</.button>
    </:footer>
  </.modal>
  <.modal id="mo-live-bottom" placement="bottom" animation="shift-up" size="md" title="placement=bottom" description="Abre perto da base.">
    <p class="m-0 text-[14px] text-muted">O modal fica rente à base da janela.</p>
    <:footer>
      <.button color="neutral" variant="soft" size="sm" phx-click={LedgerUI.close("mo-live-bottom")}>Fechar</.button>
    </:footer>
  </.modal>
  <.modal id="mo-live-alert" role="alertdialog" animation="scale" size="xs" icon="trash" icon_tone="error" title="Excluir pedido #2488?" description="Esta ação não pode ser desfeita." prevent_close>
    <:footer>
      <.button color="neutral" variant="soft" size="sm" phx-click={LedgerUI.close("mo-live-alert")}>Cancelar</.button>
      <.button color="error" size="sm" phx-click={LedgerUI.close("mo-live-alert")}>Excluir</.button>
    </:footer>
  </.modal>
  <.modal id="mo-live-chip" close_variant="chip" animation="scale" size="sm" title="Capa da loja" description="close_variant=chip">
    <div class="h-[120px] rounded-xl bg-sunken"></div>
  </.modal>
</div>

Try it: size="auto" and width

.heex
<% items = [%{n: "PED-2491", c: "Mercadinho Bom Preço", f: "Boleto 30/60/90", v: "Rota Sul", d: "12/11/2026", t: "R$ 1.284,90"}, %{n: "PED-2492", c: "Padaria Central", f: "Pix", v: "Rota Norte", d: "13/11/2026", t: "R$ 312,00"}, %{n: "PED-2493", c: "Farmácia Vida", f: "Cartão 3x", v: "Rota Sul", d: "14/11/2026", t: "R$ 2.940,10"}] %>
<div class="flex flex-wrap items-center gap-2.5">
  <.button color="neutral" variant="outline" size="sm" aria-haspopup="dialog" aria-controls="mo-auto" phx-click={LedgerUI.open("mo-auto")}>size="auto"</.button>
  <.button color="neutral" variant="soft" size="sm" aria-haspopup="dialog" aria-controls="mo-w-px" phx-click={LedgerUI.open("mo-w-px")}>{"width={780}"}</.button>
  <.button color="neutral" variant="soft" size="sm" aria-haspopup="dialog" aria-controls="mo-w-css" phx-click={LedgerUI.open("mo-w-css")}>width="min(90vw, 520px)"</.button>

  <.modal id="mo-auto" size="auto" title="Itens do pedido" description='size="auto": a largura do conteúdo'>
    <.table id="mo-auto-t" rows={items} variant="basic">
      <:col :let={o} label="Pedido" class="font-mono text-[13px] whitespace-nowrap">{o.n}</:col>
      <:col :let={o} label="Cliente" class="whitespace-nowrap">{o.c}</:col>
      <:col :let={o} label="Pagamento" class="whitespace-nowrap">{o.f}</:col>
      <:col :let={o} label="Rota" class="whitespace-nowrap">{o.v}</:col>
      <:col :let={o} label="Entrega" class="whitespace-nowrap">{o.d}</:col>
      <:col :let={o} label="Total" align="right" class="font-medium whitespace-nowrap text-ink">{o.t}</:col>
    </.table>
    <:footer>
      <.button color="neutral" variant="soft" size="sm" phx-click={LedgerUI.close("mo-auto")}>Fechar</.button>
    </:footer>
  </.modal>
  <.modal id="mo-w-px" width={780} title="Relatório" description="width={780}">
    <p class="m-0 text-[14px] text-muted">Largura de 780 px, limitada à tela. Vale mais que o <code class="font-mono text-xs">size</code>.</p>
    <:footer>
      <.button color="neutral" variant="soft" size="sm" phx-click={LedgerUI.close("mo-w-px")}>Fechar</.button>
    </:footer>
  </.modal>
  <.modal id="mo-w-css" width="min(90vw, 520px)" title="Relatório" description='width="min(90vw, 520px)"'>
    <p class="m-0 text-[14px] text-muted">Qualquer valor CSS de largura.</p>
    <:footer>
      <.button color="neutral" variant="soft" size="sm" phx-click={LedgerUI.close("mo-w-css")}>Fechar</.button>
    </:footer>
  </.modal>
</div>

Usage

<.modal id="export" show={@show}>
  <:title>Exportar relatório</:title>
  …
  <:actions>…</:actions>
</.modal>

Rules

  • Width 440 (sm), 560 (md), 720 (lg). Radius 20, lg shadow, bg-overlay scrim.
  • Footer with a bg-tray background: secondary on the left of the primary.
  • Esc and a click on the scrim close it; focus is trapped inside.

API reference

Todos os function components, atributos, valores e slots que este componente cobre.

Modal dialog for short tasks and confirmations (<.modal>).

<.button phx-click={LedgerUI.open("export")}>Export</.button>

<.modal id="export" title="Export report" description="October 2026" icon="download" size="sm">
  <p>Choose a format.</p>
  <:footer>
    <.button variant="ghost" phx-click={LedgerUI.close("export")}>Cancel</.button>
    <.button variant="primary">Export</.button>
  </:footer>
</.modal>

The title is either title="Export report" or the <:title> slot (markup); the footer is <:footer> or <:actions>; show is open under the name of Phoenix's generated modal.

It opens and closes in the browser (LedgerUI.open/close/toggle("export"), no round trip), from the server (LedgerUI.open(socket, "export")) or from the open assign. The LedgerUI.Overlay hook (priv/static/ledger_ui/hooks/overlay.js) keeps the focus inside, closes on Esc and on a click on the backdrop (unless prevent_close), returns the focus to the trigger and locks the page's scroll. on_open / on_close run however it opened or closed; as event names they push %{"id" => id} to the LiveView (or target).

The root carries data-lu-overlay: use LedgerUI.DOM.onBeforeElUpdated (see the README) so patches keep the browser's state.

inline renders the dialog in the page flow, always visible and without the hook: a static preview.

Width

size picks a fixed width (xs 320 px ... xl 960 px, full). Two ways to take another:

size="auto": the card is as wide as its content (w-max), at least the sm width (440 px) and at most the screen minus the backdrop's margin; it scrolls horizontally only when the content does not fit the screen. The height is the same as always (max-h, the body scrolls vertically).

<.modal id="items" title="Items" size="auto">
  <.table id="items-table" rows={@items}>...</.table>
</.modal>

width: an integer (px) or a CSS value, through the --lu-panel-w variable of the card, always limited to the screen. It wins over size. A string with anything but a CSS value (;, {, }, quotes, :) is ignored. card_style is merged with the variable.

<.modal id="wide" title="Report" width={780}>...</.modal>
<.modal id="wide" title="Report" width="min(90vw, 900px)">...</.modal>

size="auto" and width also apply to layout="page".

layout="page" is the dialog of the app templates: only while open, a dim lu-overlay and a div.lu-modal (header, .bd, footer) laid over the closest positioned ancestor, no hook; the page owns the state and the overlay, Esc and × push on_close. The :header slot is then the content before the ×. With phx-submit or phx-change in the attributes the dialog itself is a <form> (so its controls validate and submit); phx-target goes to the form.

<.modal>

Attr Type Default Values / notes
id (required) :string
layout :string nil nil, `,page-page: the canvas-v2 dialog (a dim overlay + a dialog withheader,.bd,footer), shown only whileopenand closed byon_close(a LiveView event or%JS{}`).
open :boolean false The server's state; the browser can still open and close it.
show :boolean false The same as open (the name of Phoenix's generated modal); either one opens it.
animation :string "fade" fade, scale, sheet, shift-down, shift-up
size :string "lg" auto, full, lg, md, sm, xl, xs - auto: the card takes the width of its content (at least the sm width, at most the screen minus the margin).
width :any nil A width: an integer (px) or a CSS value ("56rem", "min(90vw, 900px)"), limited to the screen. It wins over size. A value with anything but a CSS value is ignored.
placement :string "center" bottom, center, top
origin :string "center" bottom, center, top
blur :boolean false
backdrop_class :any nil
prevent_close :boolean false
close_button :boolean true
close_variant :string "plain" plain, chip
on_open :any nil
on_close :any nil
target :any nil
close_label :string "Close"
role :string "dialog" dialog, alertdialog
description :string nil
body_class :any nil
class :any nil Merged into the card.
icon :string nil An icon tile before the title (needs title).
icon_tone :string "neutral" accent, error, info, lime, neutral, success, warning
card_style :string nil Inline style of the card (overrides the size width; merged with the width variable).
inline :boolean false Static preview: in the page flow, always open, no hook.

Any other HTML/phx attribute goes to the root element.

Slots:

  • <:actions> - The footer's buttons; the same as :footer.
  • <:footer> - attrs: class, style
  • <:header> - attrs: variant, class, style
  • <:inner_block>
  • <:title> - The dialog's title (the title="..." attribute, a plain string, does the same); draws the header.