Feedback and status

Toast

<forma-toast>

A Popover-backed transient notification with standard perceived weight and reciprocal dismissal.

Authoring tag
<forma-toast>
Behavior owner
Native HTML
Canonical source
patterns/toast.html

Purpose

A toast is a short notification that floats above the page in the inline-end, block-end corner and does not displace layout. Forma builds it on the native Popover API: an aside with popover="manual" is shown and hidden by the browser, from popovertarget invokers or from the application calling the native popover methods. Forma supplies the placement, surface and entry/exit motion. Timing, queuing and automatic dismissal are not part of Forma; an application that wants them implements them.

Use when

  • Confirming that a background action succeeded (saved, copied, exported) where no further reading is required.
  • Offering a brief, optional follow-up such as Undo or Open next to a confirmation.
  • The message should not shift content or take permanent space in the layout.

Avoid when

  • The message reports a failure, a blocked action or an unknown outcome the user must deal with: use Alert or Operation status in the page.
  • The user must decide before continuing: use Dialog.
  • The content is contextual help attached to a control: use Popover or Tooltip / contextual hint.
  • Several notifications can appear at once: Forma toasts share one fixed position and would overlap, so consolidate them first.

Behavior to know

  • popover="manual" means no light dismiss: clicking elsewhere or pressing Escape does not close it. It stays until a hide invoker or the application hides it.
  • It renders in the top layer, so it is never clipped by overflow or covered by page content.
  • Exit shares the same duration and easing as entry.

Basic example

The smallest correct markup: the canonical pattern from patterns/toast.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal toast

Rendered from the canonical pattern file.

Live demo. 2 native actions work here and are verified by an outcome test.

HTML · Minimal toast Raw HTML for HTML · Minimal toast
<forma-toast class="forma-component-tag">
<button type="button" popovertarget="save-notification" popovertargetaction="show">Show notification</button>
<aside class="forma-toast" id="save-notification" popover="manual" role="status" data-forma-motion-weight="standard">
  <div class="forma-toast__header">
    <div>
      <h3 class="forma-toast__title">Changes saved</h3>
      <p>The current draft is stored.</p>
    </div>
    <button type="button" popovertarget="save-notification" popovertargetaction="hide" aria-label="Dismiss notification">Close</button>
  </div>
</aside>
</forma-toast>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Undo after archiving

A confirmation with a recovery action. The Undo button is a normal button the application wires up; the Close button is a native hide invoker. Both sit in the header row beside the text.

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 · Undo after archiving Raw HTML for HTML · Undo after archiving
<forma-toast class="forma-component-tag">
  <button type="button" popovertarget="toast-undo-archive-notice" popovertargetaction="show">Archive 3 threads</button>
  <aside class="forma-toast" id="toast-undo-archive-notice" popover="manual" role="status" aria-labelledby="toast-undo-archive-title">
    <div class="forma-toast__header">
      <div>
        <h3 class="forma-toast__title" id="toast-undo-archive-title">3 threads archived</h3>
        <p>They are still searchable under Archive.</p>
      </div>
      <div class="forma-cluster">
        <button type="button">Undo</button>
        <button type="button" popovertarget="toast-undo-archive-notice" popovertargetaction="hide" aria-label="Dismiss archive notification">Close</button>
      </div>
    </div>
  </aside>
</forma-toast>

Click or tap the code once to select all of it, then copy.

Scenario

Export ready with a link

A toggle invoker (no popovertargetaction) that shows and hides the same toast, and a download link inside the notification. The link is the useful content; the toast only draws attention to it.

Live demo. 3 native actions work here and are verified by an outcome test.

HTML · Export ready with a link Raw HTML for HTML · Export ready with a link
<forma-toast class="forma-component-tag">
  <button type="button" popovertarget="toast-export-ready-notice">Toggle export notice</button>
  <aside class="forma-toast" id="toast-export-ready-notice" popover="manual" role="status" aria-labelledby="toast-export-ready-title">
    <div class="forma-toast__header">
      <div>
        <h3 class="forma-toast__title" id="toast-export-ready-title">Audit export is ready</h3>
        <p><a href="#toast-export-ready-notice">audit-2026-09.csv</a> (1,000 records)</p>
      </div>
      <button type="button" popovertarget="toast-export-ready-notice" popovertargetaction="hide" aria-label="Dismiss export notification">Close</button>
    </div>
  </aside>
</forma-toast>

Click or tap the code once to select all of it, then copy.

Scenario

Lightweight copy confirmation

A single-line confirmation with no body paragraph, using the light weight for a quicker, less settled entry. Weight is presentation only and says nothing about importance.

Live demo. 2 native actions work here and are verified by an outcome test.

HTML · Lightweight copy confirmation Raw HTML for HTML · Lightweight copy confirmation
<forma-toast class="forma-component-tag">
  <button type="button" popovertarget="toast-light-copy-notice" popovertargetaction="show">Copy share link</button>
  <aside class="forma-toast" id="toast-light-copy-notice" popover="manual" role="status" data-forma-motion-weight="light" aria-labelledby="toast-light-copy-title">
    <div class="forma-toast__header">
      <h3 class="forma-toast__title" id="toast-light-copy-title">Link copied</h3>
      <button type="button" popovertarget="toast-light-copy-notice" popovertargetaction="hide" aria-label="Dismiss copy notification">Close</button>
    </div>
  </aside>
</forma-toast>

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 draft saved

A toast opened on a phone. It stays anchored to the bottom corner, clears the device safe areas and never exceeds the viewport width minus 2rem.

Live demo. 2 native actions work here and are verified by an outcome test.

Viewport width

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

What changes at narrow widths

  • The toast width is capped at min(26rem, 100vw - 2rem), so at 320px it fills the width with a 1rem margin on each side.
  • Its offset from the bottom and side respects env(safe-area-inset-*), keeping it clear of home indicators and rounded corners.
  • Long titles wrap inside the header while the Close button keeps its size as a native 44px-tall touch target.
  • It is fixed to the viewport, so it stays in place while the page scrolls and when the device rotates; it can cover content near the bottom edge until dismissed.
HTML · Mobile draft saved Raw HTML for HTML · Mobile draft saved
<forma-toast class="forma-component-tag">
  <button type="button" popovertarget="toast-mobile-saved-notice" popovertargetaction="show">Save draft</button>
  <aside class="forma-toast" id="toast-mobile-saved-notice" popover="manual" role="status" aria-labelledby="toast-mobile-saved-title">
    <div class="forma-toast__header">
      <div>
        <h3 class="forma-toast__title" id="toast-mobile-saved-title">Draft saved to this device and your account</h3>
        <p>You can continue on another device.</p>
      </div>
      <button type="button" popovertarget="toast-mobile-saved-notice" popovertargetaction="hide" aria-label="Dismiss save notification">Close</button>
    </div>
  </aside>
</forma-toast>

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.

Live demo. 2 native actions work here and are verified by an outcome test.

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
popoveraside.forma-toastmanual—Required. Makes the toast a native manual popover: hidden by default, shown in the top layer, and never light-dismissed.
idaside.forma-toastunique id—Target for invoker buttons.
popovertargetbuttonid of the toast—Native invoker. Shows, hides or toggles the toast without script.
popovertargetactionbuttonshow | hide | toggletoggleWhat the invoker does. Use hide on the Close button inside the toast.
roleaside.forma-toaststatus—Polite live-region semantics for the notification text.
aria-labelledbyaside.forma-toastid of .forma-toast__title—Names the notification by its title.
aria-labelclose buttonstring—Gives the Close button a name that says what it dismisses.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-toastBlock class—The popover surface: fixed to the inline-end/block-end corner, bordered, shadowed, with an accent inline-start border.
.forma-toast__headerElement class—Flex row that places the text block and the dismiss control side by side.
.forma-toast__titleElement class—Notification title with margins removed.
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"Presentation-only perceived mass for entry and exit: light, standard (default) or heavy. Never encodes severity or importance.
Keyboard interaction
KeysResult
Tab / Shift+TabReaches the invoker and, while the toast is open, the controls inside it. Browsers place an open popover's contents after its invoker in sequential focus order.
Enter / SpaceActivates an invoker or the Close button, showing or hiding the toast natively.
EscapeDoes nothing for a manual popover. If Escape dismissal is wanted, the application must implement it.
Events
EventDescription
beforetoggle / toggleNative popover events fired on the toast when it opens or closes. Use them in application code to track visibility or schedule an automatic hide.

Form behavior

Not a form control. Buttons inside a toast should use type="button".

States

Toast states
StateHow it is expressedPresentation
Hiddendefault for popover="manual"Not rendered (display none), transparent and offset 0.65rem downward.
Open:popover-openOpaque at its resting position in the top layer.
Entering@starting-style on :popover-openRises 0.65rem, fades in and scales from 0.99 to 1 over the inertia duration.
Exitingleaving :popover-openReverses with the same inertial duration; display and overlay stay until the exit finishes.

Accessibility

Forma provides

  • Uses native Popover API state, so open and closed are browser-authoritative and the toast is in the top layer.
  • Provides a structural accent border and shadow, and in forced colors maps the border to CanvasText.
  • Keeps dismissal on a real button with a visible label.

Your application supplies

  • Do not auto-dismiss toasts that contain actions or information the user needs; people using magnification or screen readers may not reach them in time.
  • Keep essential outcomes available elsewhere in the page as well, because announcement of a status region that just became visible varies across browsers and screen readers.
  • Give each Close button an accessible name that says what it dismisses.
  • Show at most one toast at a time; Forma does not stack or queue them.

Responsive behavior

  • Fixed to the viewport corner with a 1rem inset that grows to the device safe-area inset when larger.
  • Width is intrinsic up to min(26rem, 100vw - 2rem), so it never overflows a phone screen.
  • The header is a flex row; the text block wraps and the dismiss control stays at the end.
  • The corner uses physical right and bottom offsets, so it stays on the right in right-to-left documents too.

Motion

  • Entry uses the standard weight by default: opacity fades by perceptual interpolation (about 120ms) while position and scale settle over the inertia duration (about 215ms).
  • Exit shares the entry response (about 214ms at standard), including its damped easing.
  • display and overlay transition with allow-discrete, so the toast stays in the top layer until its exit completes; the popover state itself changes immediately.
  • data-forma-motion-weight light shortens and heavy lengthens the spatial motion. Opacity timing is independent of weight.
  • Under prefers-reduced-motion: reduce every transition is effectively instant; the toast appears and disappears 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

  • Keep the title to a short confirmation of what happened.
  • Always include a Close button with popovertargetaction="hide".
  • Pair destructive actions with Undo in the toast and keep the underlying record recoverable for a reasonable time.

Avoid

  • Reporting errors or uncertain outcomes only in a toast.
  • Using popover="auto", which would close any other open auto popover and light-dismiss on outside clicks.
  • Placing long forms or multi-step content in a toast.

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.