Alert
Inline notification embedded in the page content flow.
Import the alert component. Import the slot directives only for custom content.
import { KuiAlert } from '@kikita-labs/ui';
// Only for custom content slots:
import { KuiAlertActions, KuiAlertIcon, KuiAlertMessage, KuiAlertTitle } from '@kikita-labs/ui';Unlike kuiToast(), an alert does not float above the interface, does not dismiss itself on a timer and needs no body region. It renders next to the content it relates to.
<div class="alert-example">
<kui-alert appearance="neutral" title="Neutral" message="A plain notice without severity." />
<kui-alert appearance="info" title="Info" message="We updated the terms of service." />
<kui-alert appearance="success" title="Success" message="Your changes were saved." />
<kui-alert appearance="warning" title="Warning" message="Your access token expires in 3 days." />
<kui-alert
appearance="danger"
title="Danger"
message="The upload failed. Check your connection."
/>
</div>shape reuses the button vocabulary restricted to soft (default), outline and solid. size sm tightens padding and gap.
<div class="alert-example">
<kui-alert appearance="info" shape="soft" title="Soft" message="Tinted background and border." />
<kui-alert appearance="info" shape="outline" title="Outline" message="Transparent background." />
<kui-alert
appearance="info"
shape="solid"
title="Solid"
message="Saturated fill with on-fill text."
/>
<kui-alert appearance="info" size="sm" title="Small" message="Tighter padding and gap." />
</div>The alert is controlled: (closed) only notifies you that the close button was clicked, so render it conditionally to hide it. actionLabel adds an inline ghost button that emits (action).
<div class="alert-example">
@if (!dismissed()) {
<kui-alert
appearance="warning"
title="Session expiring"
message="Your access token expires in 3 days. Renewed {{ renewals() }} times."
actionLabel="Renew"
(action)="renew()"
(closed)="dismissed.set(true)"
/>
} @else {
<button kuiButton shape="outline" type="button" (click)="restore()">
Show the alert again
</button>
}
</div>Project kuiAlertTitle, kuiAlertIcon, kuiAlertMessage or kuiAlertActions for richer content. A projected slot takes over its area entirely and the matching input is ignored.
Check your connection and try again.
<kui-alert appearance="danger" [closable]="false">
<kui-icon kuiAlertIcon name="cloud-off" />
<span kuiAlertTitle>Upload failed <span kuiBadge appearance="danger">retrying</span></span>
<p kuiAlertMessage>Check your connection and <a href="#retry">try again</a>.</p>
<div kuiAlertActions>
<button kuiButton shape="ghost" size="xs" type="button">Retry</button>
<button kuiButton shape="ghost" size="xs" type="button">Dismiss</button>
</div>
</kui-alert>banner stretches the alert to the full container width, removes the corner radius and reduces the border to a single bottom seam. Use it for a system-wide message above the page content.
<kui-alert appearance="info" banner message="We updated the terms of service." />Set defaults.alert once for the application or for a subtree. Each option resolves as local input > defaults.alert.<option> > built-in default.
import { provideKikitaUi } from '@kikita-labs/ui';
export const appConfig: ApplicationConfig = {
providers: [
provideKikitaUi({
defaults: {
alert: {
/* options below */
},
},
}),
],
};| Name | Type | Default | Description |
|---|---|---|---|
| size | 'sm' | 'md' | — | Component size. Takes precedence over the global defaults.size. |
| shape | 'soft' | 'outline' | 'solid' | — | Default shape. |
| showIcon | boolean | — | Shows the leading status icon. |
| closable | boolean | — | Shows the close button. |
| closeIcon | KuiIconGlyph | — | Icon of the close button. Takes precedence over defaults.icons.close. See Structural Icons. |
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.
| Name | Type | Default | Description |
|---|---|---|---|
| --kui-alert-title-font-size | CSS custom property | --kui-text-sm-size | Title font size |
| --kui-alert-message-font-size | CSS custom property | --kui-text-sm-size | Message font size |
| --kui-alert-actions-gap | CSS custom property | --kui-space-3 | Actions gap |
| --kui-alert-icon-size | CSS custom property | 1.125rem (1rem for sm) | Status icon size |
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.
| Name | Type | Default | Description |
|---|---|---|---|
| close | string | — | Accessible name of the dismiss button. Default Close notification. |
Inputs verified against @kikita-labs/ui v2.0.0 public typings.
| Name | Type | Default | Description |
|---|---|---|---|
| appearance | 'neutral' | 'info' | 'success' | 'warning' | 'danger' | 'neutral' | Semantic type. Same five values as the toast. neutral never shows the built-in icon; danger is announced assertively, every other value politely. |
| shape | 'soft' | 'outline' | 'solid' | undefined | undefined | Visual weight, using the button shape vocabulary. Falls back to defaults.alert.shape, then soft. |
| size | 'sm' | 'md' | undefined | undefined | Padding and gap density. Falls back to defaults.alert.size, then the root defaults.size (sm or md only), then md. |
| banner | boolean | false | Stretches the alert to the full width of its container and removes the corner radius. |
| title | string | undefined | undefined | Optional single-line heading. Ignored when [kuiAlertTitle] is projected. Set at least one of title, message or [kuiAlertMessage]. |
| message | string | undefined | undefined | Optional supporting text below the title. Ignored when [kuiAlertMessage] is projected. |
| showIcon | boolean | undefined | undefined | Shows the built-in appearance icon (defaults.alert.showIcon, then true). neutral never shows one. Ignored when [kuiAlertIcon] is projected, which always renders. |
| closable | boolean | undefined | undefined | Shows the close button and enables (closed). Falls back to defaults.alert.closable, then true. |
| closeLabel | string | undefined | undefined | Accessible label for the close button. Falls back to the alert.close message (Close notification). |
| actionLabel | string | undefined | undefined | Label for the inline ghost action button. Ignored when [kuiAlertActions] is projected. |
| (action) | void | - | Emits when the action button is clicked. Not emitted for a projected [kuiAlertActions]. |
| (closed) | void | - | Emits when the close button is clicked. The alert never removes itself; hide it with @if. |
| [kuiAlertTitle] | content slot | - | Replaces the plain title string with arbitrary markup. |
| [kuiAlertIcon] | content slot | - | Replaces the built-in severity icon. A projected icon always renders, even for neutral, and inherits --kui-alert-icon-color. |
| [kuiAlertMessage] | content slot | - | Replaces the plain message string with arbitrary markup (links, lists). The title still renders alongside it. |
| [kuiAlertActions] | content slot | - | Replaces the single ghost action button with custom controls. kuiButton inside it picks up the appearance-tinted ghost colour. |
| KuiAlertOptions | interface | - | Shape of defaults.alert: size, shape, showIcon, closable and closeIcon. |
The alert is a static region, not an overlay, and its announcement depends on severity.
appearance="danger"rendersrole="alert"witharia-live="assertive"; every other appearance usesrole="status"witharia-live="polite". Both arearia-atomic="true".- The alert itself is not in the tab order; only its action and close buttons are.
- The close button has an accessible name from
closeLabelor thealert.closemessage. - Severity is never colour-only: info, success, warning and danger pair an icon with text. neutral has no icon because it carries no severity.
Escapedoes not close an alert.
Documented limits of the installed package.
- The close button hit target is 28px (
kuiIconButton size="xs"), below the 44px platform recommendation. The toast shares this limitation. - A formal assistive-technology review of the alert has not been run yet; see
state-coverage.mdin the library repository.