Alert
<forma-alert>
An in-page status or warning block with an icon, a heading, explanatory text and an optional action, readable without color.
- Authoring tag
<forma-alert>- Category
- Feedback and status
- Behavior owner
- Application state
- Canonical source
patterns/alert.html
Purpose
An alert places a message about the current view directly in the page flow: something changed, something needs review, or an outcome was confirmed. Forma renders it as an aside with an icon cell, a text column and an optional trailing action. The application decides when an alert exists, what it says, and which live-region role it carries; Forma only lays it out and gives it an optional entry cue when it is newly inserted.
Use when
- The message concerns the page or record the user is looking at and should stay visible until the situation changes.
- The user may need to act on the message (review, reload, retry) and the action belongs next to the explanation.
- An asynchronous result such as a save, sync or import needs to be reported in place, near the content it affects.
Avoid when
- The message is a short, transient confirmation that should not occupy layout: use Toast.
- The problem is a single form field: use Validation message under that field, and Validation summary for the form as a whole.
- The outcome of an operation is uncertain, pending or needs reconciliation: use Operation status, which carries explicit state vocabulary.
- The content is permanent explanatory guidance rather than a status: use Callout.
- The system itself is faulted and work cannot continue: use Fault banner or Fault blocking.
Behavior to know
- A thick inline-start border, a bordered icon cell and a heading give it structure that survives grayscale and forced colors.
- The icon is author-supplied text marked
aria-hidden; the heading and body carry the meaning. - Forma has no tone variants: every alert uses the same accent border. Distinguish kinds of alert with words and icon glyphs, not color.
Basic example
The smallest correct markup: the canonical pattern from patterns/alert.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal alert
Rendered from the canonical pattern file.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-alert class="forma-component-tag">
<aside class="forma-alert" role="status" data-tone="attention" data-forma-motion-weight="standard" data-forma-motion-entry>
<div class="forma-alert__icon" aria-hidden="true">!</div>
<div>
<h3 class="forma-alert__title">Review required</h3>
<p>Two values changed since this view was loaded. No update has been applied.</p>
</div>
<button type="button">Review changes</button>
</aside>
</forma-alert>
Click or tap the code once to select all of it, then copy.
Examples
Stale data warning
A persistent alert rendered with the page, so it has no entry cue. It explains that figures are out of date and offers the recovery action beside the explanation. role="status" is kept because the message is informative, not urgent.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-alert class="forma-component-tag">
<aside class="forma-alert" role="status" aria-labelledby="alert-stale-data-warning-title">
<div class="forma-alert__icon" aria-hidden="true">!</div>
<div>
<h3 class="forma-alert__title" id="alert-stale-data-warning-title">Figures last refreshed 3 hours ago</h3>
<p>The ledger sync has not completed since 09:12. Totals below may not include recent postings.</p>
</div>
<button type="button">Refresh now</button>
</aside>
</forma-alert>
Click or tap the code once to select all of it, then copy.
Confirmed outcome without an action
A newly inserted confirmation that opts into the entry cue with data-forma-motion-entry. With no action button the trailing grid column collapses and the text uses the full width.
<forma-alert class="forma-component-tag">
<aside class="forma-alert" role="status" data-forma-motion-entry aria-labelledby="alert-confirmed-save-title">
<div class="forma-alert__icon" aria-hidden="true">✓</div>
<div>
<h3 class="forma-alert__title" id="alert-confirmed-save-title">Policy published</h3>
<p>Version 14 of the retention policy is now in effect for all workspaces.</p>
</div>
</aside>
</forma-alert>
Click or tap the code once to select all of it, then copy.
Urgent interruption
A time-sensitive warning inserted by the application with role="alert", so assistive technology announces it immediately. Two actions sit in a Cluster in the trailing column. Reserve role="alert" for messages that must interrupt.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-alert class="forma-component-tag">
<aside class="forma-alert" role="alert" data-forma-motion-entry data-forma-motion-weight="standard" aria-labelledby="alert-urgent-session-expiry-title">
<div class="forma-alert__icon" aria-hidden="true">⏱</div>
<div>
<h3 class="forma-alert__title" id="alert-urgent-session-expiry-title">Your session ends in 2 minutes</h3>
<p>Unsaved changes to this assessment will be lost when the session ends.</p>
</div>
<div class="forma-cluster">
<button type="button">Stay signed in</button>
<button type="button">Save and sign out</button>
</div>
</aside>
</forma-alert>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile review prompt
The canonical review alert at phone width. The three grid columns collapse into one, so the icon, text and a full-width action stack vertically.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
What changes at narrow widths
- Below 40rem the grid becomes a single column: icon, then text, then the action.
- The trailing button stretches to the full width of the alert, giving a large touch target.
- The heading and body wrap freely inside the text column; nothing scrolls horizontally at 320px.
- The inline-start border stays, so the alert still reads as a distinct block in portrait and landscape.
<forma-alert class="forma-component-tag">
<aside class="forma-alert" role="status" aria-labelledby="alert-mobile-review-alert-title">
<div class="forma-alert__icon" aria-hidden="true">!</div>
<div>
<h3 class="forma-alert__title" id="alert-mobile-review-alert-title">Two values changed since you opened this record</h3>
<p>Another reviewer updated the credit limit and the review date. Nothing you entered has been saved yet.</p>
</div>
<button type="button">Review changes</button>
</aside>
</forma-alert>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
role | aside.forma-alert | status | alert | — | Live-region semantics chosen by the application. status is polite; alert interrupts and should be rare. Either role replaces the aside's complementary landmark role. |
aria-labelledby | aside.forma-alert | id of .forma-alert__title | — | Names the region by its heading. |
aria-hidden | .forma-alert__icon | true | — | Hides the decorative glyph so it is not read before the heading. |
data-tone | aside.forma-alert | application-defined | — | Used by the canonical pattern as an application data hook. Forma CSS does not style it; the alert looks the same for every value. |
type | button | button | — | Keeps actions from submitting a surrounding form. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-alert | Block class | — | Root grid: icon column, flexible text column and an optional trailing action column, with a thick inline-start border. |
.forma-alert__icon | Element class | — | Bordered 2rem square holding a short text glyph. Decorative; mark it aria-hidden. |
.forma-alert__title | Element class | — | Heading for the message, with its top margin removed. |
[data-forma-motion-entry] | Attribute hook | — | Opts a newly inserted alert into a short downward settle into place. Omit it on alerts rendered with the page. |
[data-forma-motion-weight] | Attribute hook | "heavy", "light", "standard" | Presentation-only perceived mass for the entry cue: light, standard (default) or heavy. Never encodes severity. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through the alert's buttons or links. The alert itself is not focusable. |
| Enter / Space | Activates the focused action button (native button behavior). |
| Event | Description |
|---|---|
click | Native click on the action buttons. Forma defines no events; the application decides what each action does and when the alert is removed. |
Form behavior
Not a form control. A button inside an alert that sits within a form must keep type="button" to avoid submitting it.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Persistent | rendered without data-forma-motion-entry | Appears in place with no movement. Use for alerts that exist when the view loads or that survive rerenders. |
| Newly inserted | data-forma-motion-entry on an element added after load | Settles down 0.5rem into place once, from @starting-style. It does not animate again while the element stays in the DOM. |
| Polite status | role="status" | Announced when content changes, without interrupting the user. |
| Urgent | role="alert" | Announced immediately on insertion. Visual presentation is identical; urgency is carried by words and role, not styling. |
Accessibility
Forma provides
- Carries meaning through a heading, body text and a structural border rather than color alone.
- Keeps the icon cell bordered in
currentColor, so it remains visible in forced colors and grayscale. - Uses native buttons, so actions are keyboard-operable with standard focus indication.
Your application supplies
- Choose the role:
statusfor most messages,alertonly when the user must be interrupted. - Insert live alerts into an existing container or add them after load; a live region present at page load is usually not announced.
- Write a heading that states the situation and body text that states the consequence and what has or has not happened.
- Do not move focus to an alert unless it blocks further work; keep it near the content it concerns.
Responsive behavior
- The root is a three-column grid (
auto minmax(0, 1fr) auto), so long text wraps within the middle column rather than pushing the action off-screen. - Below 40rem the grid collapses to one column and a direct-child action button becomes full width.
- Multiple actions should be grouped in a Cluster, which wraps when space runs out.
- The alert has no maximum width; it fills its container.
Motion
- With
data-forma-motion-entry, a newly inserted alert moves from 0.5rem above to its resting position using the shared spring easing and inertia duration (about 215ms at the standard weight). Only position animates; the text is legible from the first frame. - The cue runs once per insertion via
@starting-style. Rerendering text inside an existing alert does not replay it. data-forma-motion-weightchanges perceived mass only: light is quicker, heavy slower and more damped.- Under
prefers-reduced-motion: reducethe transition duration is effectively zero and the alert appears in place.
Motion weights
Forma motion is physics-derived: perceived mass changes how a surface accelerates and settles, never what state it is in. Compare the three presentation weights of the same markup:
Usage guidance
Do
- State what happened, what did not happen, and what the user can do.
- Remove or replace the alert when the underlying situation resolves.
- Use distinct icon glyphs and headings to separate warnings from confirmations.
Avoid
- Stacking many alerts at the top of a page; consolidate or use an Obligation panel.
- Using the entry cue on alerts that are present at page load.
- Relying on
data-toneor color to tell a warning from a confirmation.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.