Skip to content

Banner and alert

A page-level notice that keeps the last good data on screen, and an alert beside its source.

<div class="cap-banner" data-tone="warn" role="status" id="sample-warn">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.2 15.4 14H.6zM7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z"/></svg>
  <p class="cap-banner-text">Could not refresh. Showing data from 4 minutes ago.</p>
  <div class="cap-banner-actions"><button type="button" class="cap-btn">Try again</button></div>
</div>
<ul aria-label="Sites, as of 4 minutes ago">
  <li>example.edu: up, 212 ms</li>
  <li>example.net: up, 340 ms</li>
  <li>example.com: 3 failed checks</li>
</ul>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/banner.css";
import { enhance } from "capsomer/behavior/banner";

enhance();

Usage

<div class="cap-banner" data-tone="warn" role="status">
  [warning glyph]
  <p class="cap-banner-text">Could not refresh. Showing data from 4 minutes ago.</p>
  <div class="cap-banner-actions"><button type="button" class="cap-btn">Try again</button></div>
</div>

<div class="cap-banner" data-tone="warn" role="status">
  [warning glyph]
  <div class="cap-banner-body">
    <p class="cap-banner-title">Showing data from 4 minutes ago</p>
    <p class="cap-banner-text">The watcher did not answer. Nothing you changed is lost.</p>
  </div>
  <div class="cap-banner-actions"><button type="button" class="cap-btn">Try again</button></div>
</div>

<div class="cap-banner" data-tone="warn" role="status" data-cap="banner">
  [warning glyph]
  <p class="cap-banner-text">The usage numbers for D1 are a day behind.</p>
  <div class="cap-banner-actions"><button type="button" class="cap-btn" data-variant="quiet" data-cap-part="dismiss">Dismiss</button></div>
</div>

<button type="button" class="cap-btn" aria-describedby="save-error">Save schedule</button>
<div class="cap-alert" role="alert" id="save-error">
  [critical glyph]
  <span class="cap-alert-text">Could not save the schedule: the server did not answer. Save again in a minute.</span>
</div>

<div class="cap-alert" data-tone="warn" role="alert">
  [warning glyph]
  <div class="cap-alert-body">
    <p class="cap-alert-title">This token expires in 3 days</p>
    <p class="cap-alert-text">Replace it in Settings before then.</p>
  </div>
  <div class="cap-alert-action"><button type="button" class="cap-btn" data-variant="quiet">Open Settings</button></div>
</div>

Examples

Critical banner

<div class="cap-banner" data-tone="crit" role="alert" id="sample-crit">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z"/></svg>
  <p class="cap-banner-text"><b>Signed out.</b> Your session ended at 14:02. Sign in again to keep working; nothing you typed is lost.</p>
  <div class="cap-banner-actions"><a class="cap-btn" href="#s-crit">Sign in</a></div>
</div>

Inline alert beside its source

<div>
  <button type="button" class="cap-btn" aria-describedby="sample-alert">Save schedule</button>
</div>
<div class="cap-alert" role="alert" id="sample-alert">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z"/></svg>
  <span class="cap-alert-text">Could not save the schedule: the server did not answer. Your changes are kept here; save again in a minute.</span>
</div>

Banner with Dismiss

<div class="cap-banner" data-tone="warn" role="status" data-cap="banner" id="sample-dismiss">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.2 15.4 14H.6zM7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z"/></svg>
  <p class="cap-banner-text">The usage numbers for D1 are a day behind while Cloudflare's analytics catch up.</p>
  <div class="cap-banner-actions"><button type="button" class="cap-btn" data-variant="quiet" data-cap-part="dismiss">Dismiss</button></div>
</div>

Every tone

<div class="cap-banner" data-tone="neutral" role="status" id="sample-neutral">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><rect x="1.5" y="1.5" width="13" height="13" rx="2" fill="none" stroke="currentColor" stroke-width="1.6"/><path fill="currentColor" d="M7.2 7h1.6v5H7.2zM7.2 4h1.6v1.7H7.2z"/></svg>
  <p class="cap-banner-text">Neutral: the nightly report runs at 02:00 UTC.</p>
</div>
<div class="cap-banner" data-tone="info" role="status" id="sample-info">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><rect x="1.5" y="1.5" width="13" height="13" rx="2" fill="none" stroke="currentColor" stroke-width="1.6"/><path fill="currentColor" d="M7.2 7h1.6v5H7.2zM7.2 4h1.6v1.7H7.2z"/></svg>
  <p class="cap-banner-text">Notice: a new version of the watcher is rolling out to your sites.</p>
</div>
<div class="cap-banner" data-tone="ok" role="status" id="sample-ok">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1a7 7 0 1 0 0 14A7 7 0 1 0 8 1zM3.9 9l3 3 5.2-5.6-1.4-1.4-3.8 4.2-1.6-1.6z"/></svg>
  <p class="cap-banner-text">Healthy: the last pass finished with no failed checks.</p>
  <div class="cap-banner-actions"><button type="button" class="cap-btn" data-variant="quiet">View the pass</button></div>
</div>

Title, description and action

<div class="cap-banner" data-tone="warn" role="status" id="sample-title">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.2 15.4 14H.6zM7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z"/></svg>
  <div class="cap-banner-body">
    <p class="cap-banner-title">Showing data from 4 minutes ago</p>
    <p class="cap-banner-text">The watcher did not answer. Nothing you changed is lost; <a href="#s-title">read what the watcher said</a>.</p>
  </div>
  <div class="cap-banner-actions"><button type="button" class="cap-btn">Try again</button></div>
</div>

Alerts with a title and a tone

<div class="cap-alert" data-tone="crit" role="alert" id="sample-alert-title">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z"/></svg>
  <div class="cap-alert-body">
    <p class="cap-alert-title">Could not save the schedule</p>
    <p class="cap-alert-text">The cron line has six fields; a schedule takes five. Fix it and save again.</p>
  </div>
  <div class="cap-alert-action"><button type="button" class="cap-btn" data-variant="quiet">Edit the line</button></div>
</div>
<div class="cap-alert" data-tone="warn" role="alert" id="sample-alert-warn">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.2 15.4 14H.6zM7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z"/></svg>
  <div class="cap-alert-body">
    <p class="cap-alert-title">This token expires in 3 days</p>
    <p class="cap-alert-text">Replace it in Settings before then, or the uptime checks stop.</p>
  </div>
</div>
<div class="cap-alert" data-tone="neutral" role="alert" id="sample-alert-neutral">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><rect x="1.5" y="1.5" width="13" height="13" rx="2" fill="none" stroke="currentColor" stroke-width="1.6"/><path fill="currentColor" d="M7.2 7h1.6v5H7.2zM7.2 4h1.6v1.7H7.2z"/></svg>
  <div class="cap-alert-body">
    <p class="cap-alert-title">Heads up</p>
    <p class="cap-alert-text">Changes to a site's checks apply on the next pass.</p>
  </div>
</div>

Comfortable density

<div class="cap-banner" data-tone="warn" role="status" data-density="comfortable" id="sample-comfortable">
  <svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.2 15.4 14H.6zM7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z"/></svg>
  <div class="cap-banner-body">
    <p class="cap-banner-title">Showing data from 4 minutes ago</p>
    <p class="cap-banner-text">The watcher did not answer.</p>
  </div>
  <div class="cap-banner-actions"><button type="button" class="cap-btn">Try again</button></div>
</div>

API reference

Banner

PropTypeRequiredDoes
toneNoticeToneA banner with no tone is a warning.
titleReactNodeAn optional short title above the words: "Signed out".
childrenReactNodeWhat happened and what is on screen now: "Could not refresh. Showing data from 4 minutes ago."
bodyReactNodeBlock content under the words (a list, a second paragraph). It sits in a div, so a list is not inside a paragraph; children stays the inline words in a p.
actionsReactNodeThe next step, usually a Try again button.
onDismiss() => voidShown as a Dismiss button when given. Focus inside the banner moves to the page's main region first, as the HTML behavior's dismissBanner does, so it is never left on nothing when the banner goes. A banner about data that is still stale usually has none: it goes when the data is fresh again.

Alert

PropTypeRequiredDoes
toneNoticeToneAn alert with no tone is critical.
titleReactNodeAn optional short title: "Could not save the schedule".
childrenReactNodeYesPlain words, and what to do next: "Check the cron line and save again."
actionReactNode
idstringSo the source can point at it with aria-describedby.

Functions

FunctionSignatureDoes
dismissBanner(banner: HTMLElement): voidA banner's Dismiss button. The rest of a banner is CSS; its Try again is the app's own. Hides a banner and puts focus somewhere sensible if it was inside: the page's main region, made focusable for the purpose, so focus is never left on nothing.
focusMain(banner: Element): voidThe focus move itself, shared with the React Banner, whose Dismiss removes the banner instead of hiding it.
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="banner"] under root not yet attached. Returns a function that detaches.

CSS variables

VariableDefault
--_softvar(--warn-soft)
--_tonevar(--warn)

Parts and data attributes

ClassIs
.cap-alertits own class
.cap-alert-actionits own class
.cap-alert-bodyits own class
.cap-alert-textits own class
.cap-alert-titleits own class
.cap-bannerthe root
.cap-banner-actionsa part
.cap-banner-bodya part
.cap-banner-texta part
.cap-banner-titlea part
AttributeValues
data-tonecrit info neutral ok warn

Accessibility

KeyDoes
TabReaches the banner's actions in reading order; the banner itself takes no focus
Enter on DismissHides the banner; focus moves to the main region
  • Banner and alert text is --text on the tone's tint, and an alert's title is the tone's color on its tint; all 4.5:1 in both themes. The edge and glyph are 3:1 (the neutral edge is --dim).
  • Links in the words are semibold, so they are not told apart by color alone (WCAG F73 names weight as a cue).
  • A live region present at load is not announced; add the banner or alert when the failure happens.
  • Forced colors: the tint is removed, and the banner keeps its edge.