Skip to content
Kimenpre-v1documentation home
Color scheme

ki-dialog

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.

Theme for this example
Color scheme for this example
Delete draft

This permanently removes the draft.

Cancel Delete
<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>

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.

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'
});

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.

Theme for this example
Color scheme for this example
Add event
<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();
});

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

AttributePropertyTypeDefaultDescription
close-labelcloseLabelstring'Close'Accessible name for the fullscreen close button. Localize it or describe the effect of dismissing, for example "Discard and close".
close-on-backdropcloseOnBackdropbooleanfalseOpts 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-labelconfirmLabelstring | 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.
fullscreenfullscreen"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.
headingheadingstring–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.
openopenbooleanfalseReflected 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

EventDetail typeDescription
ki-closeCustomEvent<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-confirmCustomEvent<void>The user activated the confirmation button. Handle validation, submission and dismissal in the application.

Methods

MethodDescription
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

SlotDescription
(default)Dialog body content.
footerDialog actions. Dismiss using an invoker command or close().

CSS parts

PartDescription
bodyScrollable body region.
dialogInternal native dialog surface.
footerAction row, collapsed when empty.
headerFullscreen bar with the title and its controls.
headingVisible 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.

TokenDescription
--ki-button-primary-neutral-rest-bgcolor used by the button component for primary neutral rest background (MarsUI Surface/primary_med_em, brand 500).
--ki-button-primary-neutral-rest-fgcolor used by the button component for primary neutral rest foreground.
--ki-control-radius-itemCorner radius of an individual control inside a track.
--ki-control-size-mdMedium control track height, 40 CSS px at the default root size.
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-density-target-minThe 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-bgcolor used by the dialog component for backdrop background.
--ki-dialog-backdrop-filterComplete backdrop filter behind the dialog surface.
--ki-dialog-bgBase background color of the dialog. Onmars v1 uses a transparent backing beneath its glass image.
--ki-dialog-bg-imageOptional CSS background image layered over the dialog fill. Use none for a solid fill.
--ki-dialog-body-padding-block-enddimension used by the dialog component for body section padding block end (Modal compact Body: Space/5xl 20px.)
--ki-dialog-body-padding-block-startdimension used by the dialog component for body section padding block start (Modal compact Body 16414:19668: Space/5xl 20px.)
--ki-dialog-body-padding-inlinedimension used by the dialog component for body section padding inline (Modal compact Body: Space/5xl 20px.)
--ki-dialog-borderborder 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-colorcolor used by the dialog component for the dividers under the heading and above the footer (Outline/base-em).
--ki-dialog-divider-widthdimension 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-fgcolor used by the dialog component for foreground.
--ki-dialog-focus-ring-colorcolor used by the dialog component for focus ring color.
--ki-dialog-focus-ring-offsetdimension used by the dialog component for focus ring offset.
--ki-dialog-focus-ring-widthdimension used by the dialog component for focus ring width.
--ki-dialog-footer-padding-block-enddimension used by the dialog component for footer section padding block end (Modal-actions/CTAs: Space/7xl 24px.)
--ki-dialog-footer-padding-block-startdimension 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-inlinedimension used by the dialog component for footer section padding inline (Modal-actions/CTAs: Space/5xl 20px.)
--ki-dialog-fullscreen-backdrop-filterComplete backdrop filter for the fullscreen surface.
--ki-dialog-fullscreen-bgSolid raised surface for the fullscreen dialog.
--ki-dialog-fullscreen-bg-imageOptional image over the fullscreen fill.
--ki-dialog-fullscreen-fgForeground for the fullscreen dialog.
--ki-dialog-fullscreen-header-borderDivider beneath the fullscreen header.
--ki-dialog-fullscreen-header-heightMinimum block size of the fullscreen header.
--ki-dialog-gapdimension used by the dialog component for the gap between its footer actions (Modal-actions/CTAs 14158:28302: Space/xl 12px).
--ki-dialog-heading-font-familyFont family for the dialog heading. Override it to give dialogs their own heading typeface.
--ki-dialog-heading-font-sizedimension used by the dialog component for heading font size.
--ki-dialog-heading-font-weightfont weight used by the dialog component for heading font weight.
--ki-dialog-heading-letter-spacingLetter spacing for the dialog heading. Override it to tune tracking for the chosen heading typeface.
--ki-dialog-heading-line-heightdimension used by the dialog component for heading line height.
--ki-dialog-heading-padding-block-enddimension 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-startdimension used by the dialog component for heading section padding block start (Modal-header compact 14156:25916: Space/3xl 16px.)
--ki-dialog-heading-padding-inlinedimension used by the dialog component for heading section padding inline (Modal-header compact: Space/5xl 20px.)
--ki-dialog-max-widthdimension used by the dialog component for max width (surface size scale; the former ki.space.26xl reference misused the spacing scale).
--ki-dialog-min-widthdimension used by the dialog component for min width (surface size scale; the former ki.space.25xl reference misused the spacing scale).
--ki-dialog-motion-durationduration 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-easingeasing used by the dialog component for the enter transition (MarsUI decelerate curve; retires the migrated linear pair).
--ki-dialog-paddingdimension 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-radiusdimension 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-shadowDialog 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-noneFlat surfaces carry no resting shadow.
--ki-focus-primaryMarsUI 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-mdThe md spacing step for a stack or grid gap.
--ki-layout-spacing-xsThe xs spacing step for a stack or grid gap.
--ki-motion-distance-mdMotion travel distance md (8px): entrance slide offsets (e.g. dialog rise).
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-motion-easing-standard-accelerateUtility exit curve. M3 md.sys.motion.easing.standard-accelerate. onmars: the MarsUI accelerate curve (ki.easing.in).
--ki-spacing-action-hairlineWidth of the frame and divider in an action surface.
--ki-state-layer-hoverHover 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-pressedPressed 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-transparentTransparent surface backing for a background image that carries its own opacity.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-family-headingShared font family for component headings. Reassign it on a theme root to style headings independently of body copy.
--ki-typography-line-height-parasemantic dimension for typography line height para.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-weight-body-normalsemantic font weight for typography weight body normal.
--ki-typography-weight-body-semiboldsemantic font weight for typography weight body semibold.

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.

Open ki-dialog in Storybook