Alerts

Semantic feedback messages with status and density variants, copyable markup, and accessibility guidance.

Alerts communicate the outcome of an action or a condition that needs attention. The CSS supplies the surface and layout; native ARIA roles determine how assistive technology announces the message.

Status variants

<layout-stack gap="var(--space-sm)">
  <alert-message status="success" role="status">
    <span class="alert__icon" aria-hidden="true">✓</span>
    <div>
      <div class="alert__title">Changes saved</div>
      <div class="alert__body">Your profile is up to date.</div>
    </div>
  </alert-message>
  <div data-alert="true" data-status="info" role="status">
    <span class="alert__icon" aria-hidden="true">i</span>
    <div>
      <div class="alert__title">New version available</div>
      <div class="alert__body">Refresh when you are ready.</div>
    </div>
  </div>
  <div class="alert" status="warning" role="alert">
    <span class="alert__icon" aria-hidden="true">!</span>
    <div>
      <div class="alert__title">Payment expires soon</div>
      <div class="alert__body">Update your card before July 30.</div>
    </div>
  </div>
  <div class="alert" status="error" role="alert">
    <span class="alert__icon" aria-hidden="true">×</span>
    <div>
      <div class="alert__title">Upload failed</div>
      <div class="alert__body">The file is larger than 10 MB.</div>
    </div>
  </div>
</layout-stack>

<div class="alert" status="success" role="status">
  <span class="alert__icon" aria-hidden="true">✓</span>
  <div>
    <div class="alert__title">Changes saved</div>
    <div class="alert__body">Your profile is up to date.</div>
  </div>
</div>

Use role="status" for routine, polite updates. Reserve role="alert" for urgent information that should be announced immediately. Do not choose the ARIA role based only on the color.

Actions and density

<div class="alert" status="warning" density="compact" role="alert">
  <span class="alert__icon" aria-hidden="true">!</span>
  <div>
    <div class="alert__title">Session expires in 2 minutes</div>
    <div class="alert__body">Extend it to keep editing.</div>
  </div>
  <div class="alert__actions">
    <button type="button">Extend</button>
  </div>
</div>

<div class="alert" status="warning" density="compact" role="alert">
  <span class="alert__icon" aria-hidden="true">!</span>
  <div>
    <div class="alert__title">Session expires in 2 minutes</div>
    <div class="alert__body">Extend it to keep editing.</div>
  </div>
  <div class="alert__actions">
    <button type="button">Extend</button>
  </div>
</div>

Available density values are compact and spacious; omit the attribute for the default spacing.

Public API

Hosts are alert-message, [data-alert], and .alert. A custom host needs role="status" or role="alert" when announcement is appropriate. Status and density accept bare attributes, data-* attributes, and class variants.

Optional icon, title, body, and action regions accept slot="…", data-alert-…, or .alert__…. Slot attributes are light-DOM styling labels, not Shadow DOM distribution. Keep icon and action regions as direct children so parent-aware columns can detect them.

Status values:

• success
• info
• warning
• error

Useful customization variables:

• --alert-padding and --alert-gap
• --alert-background, --alert-color, and --alert-border-color
• --alert-border-width and --alert-radius
• status-specific --alert-success-*, --alert-warning-*, --alert-error-*, and --alert-info-* tokens

Accessibility checklist

• Keep meaningful text in the alert; icons should usually use aria-hidden="true".
• Use role="status" or role="alert" only when a dynamically inserted message needs announcement.
• Keep action labels specific—“Retry upload” is more useful than “OK.”
• Move focus only when the user must act before continuing; an alert role does not move focus by itself.