ki-dialog
@kimen/elements/ki-dialog- Source
- Agent reference
Use a modal dialog for destructive confirmations, blocking choices or focused input. Choose the fullscreen layout when people need room to complete a longer task.
This permanently removes the draft.
<ki-button tone="danger" commandfor="demo-dialog" command="show-modal">Delete draft</ki-button>
<ki-dialog id="demo-dialog" heading="Delete draft?"><p>This permanently removes the draft.</p><ki-button slot="footer" commandfor="demo-dialog" command="request-close" autofocus>Cancel</ki-button><ki-button slot="footer" commandfor="demo-dialog" command="close" tone="danger" variant="primary">Delete</ki-button></ki-dialog>Examples
Section titled “Examples”Dialog commands
Section titled “Dialog commands”ki-button and ki-icon-button can invoke a dialog by ID within the same
document or shadow root. Once the elements are registered, the markup handles
opening and closing. show-modal opens the dialog, close dismisses it, and
request-close first gives the dialog a chance to cancel the request. Attach
your application logic to the confirmation button to perform the deletion.
The close contract
Section titled “The close contract”Use a footer command or call close() to dismiss programmatically.
The ki-close event reports the reason in detail.reason. The
close command and an accepted request-close report command. A call
to close() reports method, Escape reports escape, and opt-in
backdrop dismissal (close-on-backdrop) reports backdrop.
Centered dismissals and programmatic closes report after focus returns.
dialog.addEventListener('ki-close', (event) => { console.log(event.detail.reason); // 'command' | 'method' | 'escape' | 'backdrop'});Fullscreen
Section titled “Fullscreen”Use fullscreen="compact" to fill windows narrower than 600 CSS pixels.
Choose always to fill the window at any width. The default, never,
uses the centered layout. The header stays visible while the body scrolls.
<ki-button commandfor="event-dialog" command="show-modal">Add event</ki-button><ki-dialog id="event-dialog" heading="New event" fullscreen="compact" confirm-label="Save" close-label="Discard and close"><ki-input label="Title" value="Design review"></ki-input><ki-input label="Date" value="24 Nov 2026"></ki-input></ki-dialog>confirm-label puts a ghost button in the fullscreen header and a primary
button in the centered footer. Handle ki-confirm to validate and save,
then call close() when the task is complete. The footer slot remains
available for additional actions.
In fullscreen, Escape and the header close button emit a cancelable
ki-close before dismissal. Call preventDefault() to keep the dialog
open, for example when the draft has unsaved changes. The button reports
method. Bind open when you need to track whether dismissal took effect.
const dialog = document.querySelector('ki-dialog#event-dialog');
dialog?.addEventListener('ki-close', (event) => { if (event.cancelable && hasUnsavedChanges()) event.preventDefault();});dialog?.addEventListener('ki-confirm', async () => { if (await saveEvent()) await dialog.close();});API reference
Section titled “API reference”When to use: destructive confirmations, blocking choices, and brief critical input that must be resolved before returning to the page. Always provide a heading, place actions in the footer slot, wire each dismissal to close() or a close command, and in destructive confirmations put autofocus on the least destructive action. Use fullscreen="compact" for longer tasks that need the whole window on compact screens.
When not to use: non-blocking feedback (ki-alert, ki-toast), supplementary hints (ki-tooltip), multi-step flows that need their own page, menus, or pickers.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
close-label | closeLabel | string | 'Close' | Accessible name for the fullscreen close button. Localize it or describe the effect of dismissing, for example "Discard and close". |
close-on-backdrop | closeOnBackdrop | boolean | false | Opts into backdrop light-dismiss. Omit this attribute for critical confirmations; close-on-backdrop="false" still enables it. When to use: low-risk dialogs where an outside click may safely dismiss. When NOT to use: destructive confirmations or decisions that should not be lost to a stray click; omit the attribute entirely rather than setting it to "false". |
confirm-label | confirmLabel | string | undefined | – | Label for the optional confirmation button. Use an action verb such as "Save". The button is in the fullscreen header or the centered footer. |
fullscreen | fullscreen | "always" | "compact" | "never" | 'never' | Layout for the native modal. Use compact to fill windows narrower than 600 CSS pixels, or always to fill any window. Use never for a centered dialog at every width. |
heading | heading | string | – | Visible dialog title and accessible-name source. Always provide a heading; an empty value intentionally leaves the native dialog unnamed. When to use: name the interrupting decision, for example "Delete account?". When NOT to use: do not omit it for production dialogs; APG modal dialogs require an accessible name. |
open | open | boolean | false | Reflected live modal state. Add it or call show() to open; remove it or call close() to close. When open, the native dialog enters the top layer and the page behind is inert. When to use: bind application state to the dialog's modal lifecycle. When NOT to use: do not set the internal native <dialog open> attribute; the host attribute is the only public source of truth. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-close | CustomEvent<KiDialogCloseDetail> | Requests dismissal on fullscreen Escape or activation of the header close button. Prevent the default on that cancelable event to keep the modal open. The button reports method and Escape reports escape. Every other dismissal path emits a noncancelable notification after close and focus restoration. Use open to observe the modal's live state. |
ki-confirm | CustomEvent<void> | The user activated the confirmation button. Handle validation, submission and dismissal in the application. |
Methods
| Method | Description |
|---|---|
close() => Promise<void> | Closes the dialog and reports method. No-op when already closed. Equivalent to removing the host open attribute. Footer actions never close automatically; wire them to this method or an invoker command. When to use: resolve footer actions, programmatic dismissals, and application-controlled cancellation. When NOT to use: do not use for Escape or backdrop bookkeeping; those paths set their own close reasons. |
show() => Promise<void> | Opens the dialog modally. No-op when already open. Equivalent to adding the host open attribute. When to use: call from the invoker that should receive focus again after close. When NOT to use: do not call repeatedly to refresh content; update slotted content directly while open. |
Slots
| Slot | Description |
|---|---|
| (default) | Dialog body content. |
footer | Dialog actions. Dismiss using an invoker command or close(). |
CSS parts
| Part | Description |
|---|---|
body | Scrollable body region. |
dialog | Internal native dialog surface. |
footer | Action row, collapsed when empty. |
header | Fullscreen bar with the title and its controls. |
heading | Visible h2 title, rendered only when heading is non-empty. |
CSS custom properties
The public styling contract of ki-dialog: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-button-primary-neutral-rest-bg | color used by the button component for primary neutral rest background (MarsUI Surface/primary_med_em, brand 500). |
--ki-button-primary-neutral-rest-fg | color used by the button component for primary neutral rest foreground. |
--ki-control-radius-item | Corner radius of an individual control inside a track. |
--ki-control-size-md | Medium control track height, 40 CSS px at the default root size. |
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-dialog-backdrop-bg | color used by the dialog component for backdrop background. |
--ki-dialog-backdrop-filter | Complete backdrop filter behind the dialog surface. |
--ki-dialog-bg | Base background color of the dialog. Onmars v1 uses a transparent backing beneath its glass image. |
--ki-dialog-bg-image | Optional CSS background image layered over the dialog fill. Use none for a solid fill. |
--ki-dialog-body-padding-block-end | dimension used by the dialog component for body section padding block end (Modal compact Body: Space/5xl 20px.) |
--ki-dialog-body-padding-block-start | dimension used by the dialog component for body section padding block start (Modal compact Body 16414:19668: Space/5xl 20px.) |
--ki-dialog-body-padding-inline | dimension used by the dialog component for body section padding inline (Modal compact Body: Space/5xl 20px.) |
--ki-dialog-border | border used by the dialog component for border (MarsUI 1px solid Outline/base_em Black/3 light / White/3 dark; retires the migrated Black/5 foundation reference). |
--ki-dialog-divider-color | color used by the dialog component for the dividers under the heading and above the footer (Outline/base-em). |
--ki-dialog-divider-width | dimension used by the dialog component for the dividers under the heading and above the footer (Modal-header and Modal-actions 1px strokes). Zero removes them. |
--ki-dialog-fg | color used by the dialog component for foreground. |
--ki-dialog-focus-ring-color | color used by the dialog component for focus ring color. |
--ki-dialog-focus-ring-offset | dimension used by the dialog component for focus ring offset. |
--ki-dialog-focus-ring-width | dimension used by the dialog component for focus ring width. |
--ki-dialog-footer-padding-block-end | dimension used by the dialog component for footer section padding block end (Modal-actions/CTAs: Space/7xl 24px.) |
--ki-dialog-footer-padding-block-start | dimension used by the dialog component for footer section padding block start (Modal-actions/CTAs 14158:28302: Space/7xl 24px, below the divider.) |
--ki-dialog-footer-padding-inline | dimension used by the dialog component for footer section padding inline (Modal-actions/CTAs: Space/5xl 20px.) |
--ki-dialog-fullscreen-backdrop-filter | Complete backdrop filter for the fullscreen surface. |
--ki-dialog-fullscreen-bg | Solid raised surface for the fullscreen dialog. |
--ki-dialog-fullscreen-bg-image | Optional image over the fullscreen fill. |
--ki-dialog-fullscreen-fg | Foreground for the fullscreen dialog. |
--ki-dialog-fullscreen-header-border | Divider beneath the fullscreen header. |
--ki-dialog-fullscreen-header-height | Minimum block size of the fullscreen header. |
--ki-dialog-gap | dimension used by the dialog component for the gap between its footer actions (Modal-actions/CTAs 14158:28302: Space/xl 12px). |
--ki-dialog-heading-font-family | Font family for the dialog heading. Override it to give dialogs their own heading typeface. |
--ki-dialog-heading-font-size | dimension used by the dialog component for heading font size. |
--ki-dialog-heading-font-weight | font weight used by the dialog component for heading font weight. |
--ki-dialog-heading-letter-spacing | Letter spacing for the dialog heading. Override it to tune tracking for the chosen heading typeface. |
--ki-dialog-heading-line-height | dimension used by the dialog component for heading line height. |
--ki-dialog-heading-padding-block-end | dimension used by the dialog component for heading section padding block end (Modal-header compact: Space/3xl 16px, above the divider.) |
--ki-dialog-heading-padding-block-start | dimension used by the dialog component for heading section padding block start (Modal-header compact 14156:25916: Space/3xl 16px.) |
--ki-dialog-heading-padding-inline | dimension used by the dialog component for heading section padding inline (Modal-header compact: Space/5xl 20px.) |
--ki-dialog-max-width | dimension used by the dialog component for max width (surface size scale; the former ki.space.26xl reference misused the spacing scale). |
--ki-dialog-min-width | dimension used by the dialog component for min width (surface size scale; the former ki.space.25xl reference misused the spacing scale). |
--ki-dialog-motion-duration | duration used by the dialog component for the enter transition (MarsUI moderate step 240ms; retires the migrated 0ms token that disabled the @starting-style fade). |
--ki-dialog-motion-easing | easing used by the dialog component for the enter transition (MarsUI decelerate curve; retires the migrated linear pair). |
--ki-dialog-padding | dimension used by the dialog component for the room it keeps from the viewport edges when its width or height is clamped. Each section pads itself (heading, body and footer padding tokens). |
--ki-dialog-radius | dimension used by the dialog component for radius (MarsUI compact Modal master 16414:19665: Radius/big_component/radius_sm 20px; the large variant anchors 24px big_component/radius_md). |
--ki-dialog-shadow | Dialog elevation: MarsUI elevation ramp level e4 (brief §5, high modal surface; replaces the migrated approximation). material3 keeps its own e3 override (M3 dialog = level3). |
--ki-elevation-none | Flat surfaces carry no resting shadow. |
--ki-focus-primary | MarsUI Focus/primary: 3px spread focus ring of Outline/primary_base_em_alpha, read from the Figma master as #845abe33 = brand 500 at 20% (Kimen name: outline.primary-base-em-alpha / brand.500-alpha-2). The previous 40% (outline.primary-low-em-alpha / brand.500-alpha-4) came from specs/002-ki-button/design-extraction.md §2.5, which read the alpha off the Dark canvas mode and recorded it as the Light value; the ring shipped 2x too strong in light and 2.8x in dark across twelve components. |
--ki-layout-spacing-md | The md spacing step for a stack or grid gap. |
--ki-layout-spacing-xs | The xs spacing step for a stack or grid gap. |
--ki-motion-distance-md | Motion travel distance md (8px): entrance slide offsets (e.g. dialog rise). |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-motion-easing-standard-accelerate | Utility exit curve. M3 md.sys.motion.easing.standard-accelerate. onmars: the MarsUI accelerate curve (ki.easing.in). |
--ki-spacing-action-hairline | Width of the frame and divider in an action surface. |
--ki-state-layer-hover | Hover interaction state layer. M3 md.sys.state.hover.state-layer-opacity: 8% of the on-color. onmars: the MarsUI hover_overlay (White/5 light, Black/5 dark). |
--ki-state-layer-pressed | Pressed interaction state layer. M3 md.sys.state.pressed.state-layer-opacity: 12% of the on-color (same as focus). onmars: MarsUI overlay one step above hover_overlay (White/8 light, Black/8 dark). |
--ki-surface-transparent | Transparent surface backing for a background image that carries its own opacity. |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-family-heading | Shared font family for component headings. Reassign it on a theme root to style headings independently of body copy. |
--ki-typography-line-height-para | semantic dimension for typography line height para. |
--ki-typography-size-body-1 | semantic dimension for typography size body 1. |
--ki-typography-weight-body-normal | semantic font weight for typography weight body normal. |
--ki-typography-weight-body-semibold | semantic font weight for typography weight body semibold. |
Accessibility
Section titled “Accessibility”Always provide a heading — APG modal dialogs require an accessible name.
In destructive confirmations put autofocus on the least destructive
action. An opener with command="show-modal" exposes the dialog popup and
its expanded state, then regains focus after close. When using show(), call
it from the control that should receive focus again. Non-blocking feedback belongs to
ki-alert; supplementary hints to
ki-tooltip.