Surfaces

Stable - @kikita-labs/ui v2.0.0

Dialog

Typed modal overlay opened imperatively via kuiDialog(), not rendered as a bound component instance. Built on Angular CDK Overlay.

Import

Import the inject-function factory and dialog-host contract types from the published package entrypoint.

dialog.ts
import {
  KUI_DIALOG_CONTEXT,
  KuiButton,
  KuiDialogContext,
  KuiDialogHost,
  kuiDialog,
} from '@kikita-labs/ui';

// Import runtime styles once, application-wide:
import '@kikita-labs/ui/styles';

Usage

Open in Playground

Implement KuiDialogHost on your dialog component, inject KUI_DIALOG_CONTEXT to read data and close, then create a typed opener with kuiDialog() and call it with data to open. The returned observable emits the typed result once and completes.

<div class="basic-dialog-example">
  <button kuiButton type="button" (click)="invite()">Invite teammate</button>
  @if (lastResult()) {
    <p class="basic-dialog-example__result">Last result: {{ lastResult() }}</p>
  }
</div>

Sizes

size selects a panel width preset: auto sizes to content with a 320px minimum, sm is 400px, md is 560px (default), lg is 720px, and fullscreen fills the viewport without the panel border, radius or shadow.

<div class="dialog-sizes-example">
  @for (size of sizes; track size) {
    <button kuiButton type="button" shape="outline" (click)="open(size)">{{ size }}</button>
  }
</div>

Confirm

kuiConfirm() opens a pre-built confirmation dialog without a custom component. It always sets dismissable: false and closable: false, so the user must pick Confirm or Cancel. It resolves Observable<boolean>.

<div class="dialog-confirm-example">
  <button kuiButton type="button" appearance="danger" (click)="deleteRecord()">
    Delete record
  </button>
  @if (lastResult()) {
    <p class="dialog-confirm-example__result">Last result: {{ lastResult() }}</p>
  }
</div>

Provider defaults

Set defaults.dialog once for the application or for a subtree. Each option resolves as local input > defaults.dialog.<option> > built-in default.

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        dialog: {
          /* options below */
        },
      },
    }),
  ],
};
NameTypeDefaultDescription
closableboolean — Shows the close button in the header.
size'auto' | 'sm' | 'md' | 'lg' | 'fullscreen' — Dialog width preset.
appearance'default' | 'danger' | 'warning' — Visual intent of the dialog.
dismissableboolean — Closes the dialog on Escape and on a backdrop click.
closeIconKuiIconGlyph — Icon of the close button. Takes precedence over defaults.icons.close. See Structural Icons.

Theming tokens

Set any of these on the component or an ancestor to restyle one part. Each token is optional: when it is not set, the part uses the role or scale token in the default column.

NameTypeDefaultDescription
--kui-dialog-colorCSS custom property--kui-color-textColor
--kui-dialog-header-borderCSS custom property--kui-color-borderHeader border color
--kui-dialog-title-colorCSS custom property--kui-color-textTitle color
--kui-dialog-close-colorCSS custom property--kui-color-text-secondaryClose color
--kui-dialog-close-bg-hoverCSS custom property--kui-color-state-hoverClose background, hover
--kui-dialog-close-color-hoverCSS custom property--kui-color-textClose color, hover
--kui-dialog-body-colorCSS custom property--kui-color-textBody color
--kui-dialog-footer-borderCSS custom property--kui-color-borderFooter border color
NameTypeDefaultDescription
--kui-dialog-header-gapCSS custom property--kui-space-3Header gap
--kui-dialog-close-radiusCSS custom property--kui-radius-smClose corner radius
--kui-dialog-body-font-sizeCSS custom property--kui-text-sm-sizeBody font size
--kui-dialog-footer-gapCSS custom property--kui-space-2Footer gap
--kui-dialog-min-width-autoCSS custom property320pxMinimum width of the auto-sized dialog
--kui-dialog-icon-sizeCSS custom property20pxHeader icon slot size
--kui-dialog-close-sizeCSS custom property28pxClose button size

Messages

Every text the component owns (accessible names, visible words, announcements) is a typed message with an English default. Override it for the application with provideKikitaUi({ messages }), or for a subtree with provideKuiMessages.

NameTypeDefaultDescription
labelstring — Accessible name of a dialog that has no title. Default Dialog.
confirmstring — Confirm button of kuiConfirm. Default OK.
cancelstring — Cancel button of kuiConfirm. Default Cancel.

API

API verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
kuiDialog(component, config?)(component: Type<TComponent>, config?: Omit<KuiDialogConfig, "data">) => (data: TData) => Observable<TResult | undefined>-Inject-function factory. Call once per injection context to get a typed opener bound to that component.
KuiDialogHost<TResult, TData>interface-Contract your dialog component implements. Requires a dialogContext property injected from KUI_DIALOG_CONTEXT.
KUI_DIALOG_CONTEXTInjectionToken<KuiDialogContext<TResult, TData>>-Injected inside the dialog component to read data and close the dialog.
dialogContext.dataTData-Data passed via the opener call, e.g. openDialog(data).
dialogContext.closableboolean-Mirrors KuiDialogConfig.closable. Informational only -- the container renders .kui-dialog-close itself when true.
dialogContext.appearanceKuiDialogAppearance-Mirrors KuiDialogConfig.appearance, for coloring a custom icon if needed.
dialogContext.close(result?)(result?: TResult) => void-Closes the dialog, optionally emitting a typed result to the opener subscription.
KuiDialogConfig.dataTDataundefinedAvailable on the low-level config type; kuiDialog() passes feature data through the returned opener function instead.
KuiDialogConfig.size'auto' | 'sm' | 'md' | 'lg' | 'fullscreen''md'Panel width preset: auto (min 320px), sm (400px), md (560px), lg (720px), fullscreen (fills the viewport, no border, radius or shadow). Falls back to defaults.dialog.size.
KuiDialogConfig.appearance'default' | 'danger' | 'warning''default'Colors .kui-dialog-icon via a CSS variable. Has no other visual effect. Falls back to defaults.dialog.appearance.
KuiDialogConfig.dismissablebooleantrueAllows Escape and backdrop click to close the dialog. Falls back to defaults.dialog.dismissable.
KuiDialogConfig.closablebooleantrueShows the .kui-dialog-close button the container renders automatically, absolutely positioned top-right of the panel.
KuiDialogRef<TResult>class-Return type of kuiDialog(component, config). Calling it with data opens the dialog and returns Observable<TResult | undefined>.
kuiConfirm()() => (config: KuiConfirmConfig) => Observable<boolean>-Inject-function for a pre-built confirmation dialog. No custom component required.
KuiConfirmConfig.titlestringrequiredHeader text.
KuiConfirmConfig.messagestring | undefined-Body text.
KuiConfirmConfig.appearanceKuiDialogAppearance'default'Icon color and button tone.
KuiConfirmConfig.confirmLabelstring | undefineddialog.confirm messageConfirm button label. Defaults to the dialog.confirm message (OK).
KuiConfirmConfig.cancelLabelstring | undefineddialog.cancel messageCancel button label. Defaults to the dialog.cancel message (Cancel).
.kui-dialog-iconCSS class-Add to an SVG placed before .kui-dialog-title inside .kui-dialog-header. Fixed 20x20px, colored via appearance.
--kui-dialog-bgCSS custom propertyvar(--kui-color-surface-elevated)Panel background color.
--kui-dialog-borderCSS custom propertyvar(--kui-color-border)Panel border color.
--kui-dialog-radiusCSS custom propertyvar(--kui-radius-lg)Panel corner radius.
--kui-dialog-shadowCSS custom propertyvar(--kui-shadow-lg)Panel elevation shadow.
--kui-dialog-backdropCSS custom propertyoklch(0 0 0 / 0.5)Backdrop fill color.
KuiDialogOptions / KuiModalSurfaceOptionsinterfaces-Shape of defaults.dialog (closable, size, appearance, dismissable, closeIcon), built on the base interface shared with the drawer. Options are read each time a dialog opens, so an open dialog keeps what it opened with.

Accessibility

Dialog traps focus and blocks page scroll while open, matching native modal expectations.

  • The panel renders role="dialog" and aria-modal="true" automatically.
  • The panel uses aria-labelledby when .kui-dialog-title exists in your content, and falls back to aria-label="Dialog" otherwise. Always include a .kui-dialog-title heading.
  • Focus is trapped inside the dialog via CDK cdkTrapFocus and returns to the opening element after close.
  • Escape and backdrop click close the dialog by default; set dismissable: false for actions the user must explicitly resolve, as kuiConfirm() does.
  • Backdrop dismissal only applies when the pointer interaction starts on the backdrop; selecting text or dragging from inside the panel cannot close the dialog accidentally.
  • Page scroll is blocked via the CDK block scroll strategy while any dialog is open.
  • A toast shown while a dialog is open appears above it, in the browser top layer, so its message is not hidden behind the backdrop.
  • Without a .kui-dialog-title the accessible name comes from the dialog.label message (Dialog), and the confirm and cancel buttons of kuiConfirm() from the dialog.confirm and dialog.cancel messages.
  • The panel renders .kui-dialog-close itself, top-right of the header, when closable is true (the default); the header reserves space for it automatically. dialogContext.closable is retained for informational use only.

Migrating to 2.0

Consumer-visible changes of @kikita-labs/ui 2.0 for Dialog.

  • The imports are KuiButton and the rest of the renamed classes; ng update @kikita-labs/ui renames them. KuiDialogContext, KUI_DIALOG_CONTEXT and kuiDialog() keep their names.
  • Defaults come from defaults.dialog and are read each time a dialog opens. The fullscreen size is new.
  • The backdrop uses the --kui-color-scrim role, the layer comes from --kui-z-dialog (it was a literal 100) only where the browser lacks the Popover API, and the close button and icon sizes are tokens.
  • Button and close-mark icons are drawn by the shared structural icon renderer, and the accessible name and confirm labels come from the dialog messages.