Components Modals

Modals

Centered overlay dialog with scrim, scroll-lock, focus-trap, ESC-to-close, and click-outside-to-close. The generic <koala-modal> covers edit forms and richer interactions; <koala-confirm-modal> is a specialised variant for short yes/no destructive prompts.

<koala-modal>

Canonical

<div x-data="{ canonicalOpen: false }">
    <button koala-btn="Primary" x-on:click="canonicalOpen = true">Edit branch</button>
    <koala-modal flag="canonicalOpen" title="Edit branch" size="Medium">
        <koala-modal-content>
            @* form fields *@
        </koala-modal-content>
        <koala-modal-footer>
            <button koala-btn="Secondary" x-on:click="canonicalOpen = false">Cancel</button>
            <button koala-btn="Primary" x-on:click="canonicalOpen = false">Save</button>
        </koala-modal-footer>
    </koala-modal>
</div>

Click to open a real <koala-modal>. ESC closes; backdrop dismisses; the parent x-data declares canonicalOpen: false and the trigger flips it.

Confirm modal

<koala-confirm-modal> is a thin shell around <koala-modal> that pre-wires the icon circle, posts the form to a Razor handler, and ships verb-led Confirm / Cancel buttons. Use it for short irreversible prompts; reach for the generic modal when the body needs more than a paragraph. <koala-confirm-modal> source

<div x-data="{ confirmOpen: false }">
    <button koala-btn="Danger" x-on:click="confirmOpen = true">Cancel quote</button>
    <koala-confirm-modal flag="confirmOpen" variant="Danger"
                         title="Cancel quote?"
                         form-handler="Cancel"
                         confirm-text="Yes, cancel"
                         cancel-text="Keep it">
        <p class="text-on-surface-muted text-center mb-6">This action cannot be undone.</p>
    </koala-confirm-modal>
</div>

Sub-components

3 helpers

Tag	Attributes	Notes
<koala-modal-header>	<code>flag</code> (string)	Optional. Use only when the title needs siblings (status badge, version picker). The plain `title` attribute on `<koala-modal>` covers the common case and renders this automatically. `flag` mirrors the parent modal's Alpine flag so the close-X knows what to clear.
<koala-modal-content>	<code>class</code> (string?)	Scrollable middle section. Adds `flex-1 overflow-y-auto p-6` by default. Pass `class` to layer additional utilities.
<koala-modal-footer>	<code>class</code> (string?)	Sticky-bottom action row. Adds `flex justify-end gap-3 p-6 border-t border-outline-variant`. Right-align is the default; pass `class="justify-between"` for split actions.

Variants

2 variants

Danger

variant="Danger"

Primary

variant="Primary"

With audit reason

reason-field-name="…"

States

3 states

Closed

Click to open the dialog

ESC

ESC dismiss

ESC closes via x-on:keydown.escape.window

Backdrop dismiss

Click outside the dialog to close

Props

11 attributes

Attribute	Values	Notes
flag	string	Alpine variable controlling open/closed. Defaults to `confirmOpen`. The parent `x-data` must declare it.
variant	Danger, Primary	Icon-circle colour, confirm-button colour, and default icon.
title	string	Bold heading above the body content.
icon	IconName	Override the variant's default icon.
form-handler	string	Razor page handler name. Posts to `?handler={name}`.
form-action	URL	Override the action URL entirely.
form-route-id	Guid	Appended as `?id=` to the handler URL.
form-route-note-id	Guid	Appended as `?noteId=` when present.
form-target	string	Alpine-AJAX target element id. Defaults to `main`.
form-target-push	bool	Defaults to `true`. Pushes a new history entry on swap.
confirm-text / cancel-text	string	Button labels. Default to `Confirm` / `Cancel`.

Do & don't

Do Use verb-led button labels that describe the outcome. “Yes, cancel” and “Keep it” read as decisions, not OK/Cancel boilerplate.

Don't Don't use OK / Cancel. They force the user to re-read the body to learn what each button does.

Generic modal

<koala-modal> with optional <koala-modal-header> / <koala-modal-content> / <koala-modal-footer> children. Owns the scrim, scroll-lock, focus-trap, ESC-to-close, and click-outside-to-close. Use this for richer interactions where the confirm modal isn't expressive enough.

Quick form

title="Edit branch"

Custom header

<koala-modal-header> child

Sizes

size	Use for
Small (default)	max-w-md — confirm modals, short forms (1–3 fields).
Medium	max-w-lg — standard edit modals (3–6 fields).
Large	max-w-2xl — detail views, side-by-side fields.
ExtraLarge	max-w-4xl — embedded maps / tables.

ESC close affordance

Shared "esc" pill + X close button widget that appears in modal and tray headers. Use directly when building a custom dialog header; the standard <koala-modal> and <koala-tray-header> include it automatically.

<koala-esc-close>

esc

Attribute	Notes
on-click	Alpine expression to run on click. Wins over `dispatch`.
dispatch	Alpine event name to dispatch on click. Defaults to `close-side-tray` when both are omitted.
aria-label	Accessibility label on the X button. Defaults to `Close`.