Feedback and status

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>
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.

Canonical

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.

HTML · Minimal alert Raw HTML for HTML · Minimal alert
<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

Scenario

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.

HTML · Stale data warning Raw HTML for HTML · Stale data warning
<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.

Scenario

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.

HTML · Confirmed outcome without an action Raw HTML for HTML · Confirmed outcome without an action
<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.

Scenario

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.

HTML · Urgent interruption Raw HTML for HTML · Urgent interruption
<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 example

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Mobile review prompt Raw HTML for HTML · Mobile review prompt
<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.

Baseline

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
roleaside.forma-alertstatus | 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-labelledbyaside.forma-alertid of .forma-alert__title—Names the region by its heading.
aria-hidden.forma-alert__icontrue—Hides the decorative glyph so it is not read before the heading.
data-toneaside.forma-alertapplication-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.
typebuttonbutton—Keeps actions from submitting a surrounding form.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-alertBlock class—Root grid: icon column, flexible text column and an optional trailing action column, with a thick inline-start border.
.forma-alert__iconElement class—Bordered 2rem square holding a short text glyph. Decorative; mark it aria-hidden.
.forma-alert__titleElement 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.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the alert's buttons or links. The alert itself is not focusable.
Enter / SpaceActivates the focused action button (native button behavior).
Events
EventDescription
clickNative 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

Alert states
StateHow it is expressedPresentation
Persistentrendered without data-forma-motion-entryAppears in place with no movement. Use for alerts that exist when the view loads or that survive rerenders.
Newly inserteddata-forma-motion-entry on an element added after loadSettles down 0.5rem into place once, from @starting-style. It does not animate again while the element stays in the DOM.
Polite statusrole="status"Announced when content changes, without interrupting the user.
Urgentrole="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: status for most messages, alert only 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-weight changes perceived mass only: light is quicker, heavy slower and more damped.
  • Under prefers-reduced-motion: reduce the 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:

lightpresentation only
standardpresentation only
heavypresentation only

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-tone or 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.