Anatomy
Description text goes here.
- 1 Icon — a decorative indicator chosen from the variant; provides a second cue alongside color.
- 2 Content — a title and an optional description.
- 3 Dismiss button — optional; hides the alert when activated.
Options
Variants
A neutral message with no specific status.
Here is some helpful context.
Your action completed successfully.
Something went wrong. Please try again.
Please review the following before proceeding.
Variants select an appearance and a default icon; they do not infer meaning from the text. Choose the variant and wording together.
Sizes
Default size.
Small size.
Container scaling
Use the Scale switch beside Light/Dark in the preview above, or set data-scale="small|medium|large" on a containing element. Font size, line height, spacing and corner radius inherit that context. A local size="sm" remains smaller within the chosen context; it does not cancel the container scale. Border width stays fixed.
Container small.
Container medium.
Container large.
The default context is medium. A nested container replaces the inherited context explicitly, without multiplying the parent context again. Brand and light/dark mode remain independent.
Table of options
| Custom Element | Nunjucks | Values and defaults |
|---|---|---|
variant | variant | Empty default (neutral), info, positive, negative, notice. Unsupported values fall back to the neutral default. |
title | title | Bold heading text. Optional; omitted when empty. |
description | description | Body text. Optional; omitted when empty. |
icon | icon | Icon name override. Defaults to a variant-appropriate icon; the neutral default has no icon unless set. |
size | size | md (default) or sm. Relative to the inherited container scale. |
dismissible | dismissible | false (default) or present/true. Adds a dismiss button. |
Behaviors
Activate the close button to hide this alert.
Dismiss
When dismissible is set, a close button appears. Activating it adds the is-hidden class and the Custom Element dispatches a uif-dismiss event. Dismissal does not remove the element from the DOM.
Title-only
The description is optional. When omitted, the title occupies the content area on its own.
Usage guidelines
Your reservation has been saved.
Do
Use positive for confirmed actions and successful outcomes, with wording that matches.
Your reservation has been saved.
Don't
Do not pair a success message with the negative variant — it signals an error and misleads.
Place the alert next to the content it concerns. Keep a single clear message per alert and avoid stacking many alerts in one region.
Content standards
- Keep titles short, around 3–7 words, in sentence case.
- Write descriptions in plain language; make them concise and actionable.
- Do not repeat the title content in the description.
- Provide localized text. The component does not translate content.
Keyboard interactions
| Key | Action |
|---|---|
| Tab | Moves focus to the dismiss button, when present. |
| Enter / Space | Activates the focused dismiss button. |
Without a dismiss button the alert has no interactive controls and does not enter the tab order.
Accessibility
- The container uses
role="alert"so assistive technologies announce the message when it is inserted. - Icons are decorative and carry
aria-hidden="true". - The dismiss button has an explicit
aria-label="Dismiss"and a visible focus indicator. - Color is not the only cue: the variant icon and the wording carry the meaning (WCAG 1.4.1).
- Rapidly inserting or updating alerts can cause repeated announcements; insert them deliberately.
Implementation
Import the individual module once, or use the aggregate ui-foundations/elements entry.
import "ui-foundations/elements/ui-inline-alert";
<uif-inline-alert variant="info" title="Information" description="Here is some helpful context."></uif-inline-alert>
<uif-inline-alert variant="negative" title="Error" description="Something went wrong." dismissible></uif-inline-alert>
For static HTML without Custom Element JavaScript, use the macro:
{% import "macros/ui.njk" as uif %}
{{ uif.inlineAlert(title="Information", description="Here is some helpful context.", variant="info", dismissible=true) }}
The macro and Custom Element emit the same markup: a .uif-inline-alert container with .uif-inline-alert-icon, .uif-inline-alert-content (.uif-inline-alert-title and .uif-inline-alert-description) and an optional .uif-inline-alert-dismiss button. Title and description text are escaped.
The scale belongs to the container, not to the size attribute:
<div data-scale="large">
<uif-inline-alert size="sm" variant="info" title="Information"></uif-inline-alert>
</div>
Theming
Use the brand and mode switches in the preview above. Visual values come from the pattern's --uif-inline-alert-* slots, which alias existing Semantic roles: surfaces, borders and content colors per variant. Set data-brand="a", "b" or "c" and data-mode="light" or "dark" on the root element. Consumers own activation of these contexts. See Design Tokens.
Tokens
| Token |
|---|
--_uif-context-scale |
--_uif-local-scale |
--_uif-scale-small |
--uif-inline-alert-border-radius |
--uif-inline-alert-border-size |
--uif-inline-alert-content-gap |
--uif-inline-alert-default-border-color |
--uif-inline-alert-default-container-background |
--uif-inline-alert-default-text-color |
--uif-inline-alert-font-family |
--uif-inline-alert-font-size |
--uif-inline-alert-gap |
--uif-inline-alert-info-border-color |
--uif-inline-alert-info-container-background |
--uif-inline-alert-info-text-color |
--uif-inline-alert-line-height |
--uif-inline-alert-negative-border-color |
--uif-inline-alert-negative-container-background |
--uif-inline-alert-negative-text-color |
--uif-inline-alert-notice-border-color |
--uif-inline-alert-notice-container-background |
--uif-inline-alert-notice-text-color |
--uif-inline-alert-padding-block |
--uif-inline-alert-padding-inline |
--uif-inline-alert-positive-border-color |
--uif-inline-alert-positive-container-background |
--uif-inline-alert-positive-text-color |
--uif-inline-alert-title-font-weight |
--uif-semantic-color-focus |
--uif-semantic-size-border-default |
--uif-semantic-size-border-thick |
Design checklist
Automated checks cover markup, token resolution and naming. They do not certify complete accessibility or live design parity.
Optional action
Use action-label / actionLabel to add one recovery action inside the content region. It renders as a button, or as a link when action-href / actionHref is provided. Allowed URL prefixes are http:, https:, mailto:, tel:, / and #; unsupported URLs fall back to #. Action text is escaped.
<uif-inline-alert variant="negative" title="Could not save" action-label="Try again"></uif-inline-alert>
{{ uif.inlineAlert(title="Session expired", actionLabel="Sign in", actionHref="/login") }}