v3.0.0
HeaderAlert

A page-level status banner pinned to the top of the screen. Announces a critical, screen-level state with a centered title + subtitle and an optional close control. Three tones: Error, Warning, Success.

-- -- -- 3.0.7
Title
Subtitle

Overview

HeaderAlert is a full-width status banner anchored to the top of the screen — it spans the system status-bar area and sits above the app's own header. It announces a critical, screen-level state the user must notice immediately: a lost connection.

  • 1
    Error
  • 2
    Warning
  • 3
    Success
No internet connection
Some features may be unavailable
1
Weak GPS signal
Your location may be inaccurate
2
Payment received
Your trip is confirmed
3

States

HeaderAlert is a status container; its only interactive element is the optional close control. Each tone below is the same structure with a different accent fill.

Error

No internet connection
Some features may be unavailable
1
2
3
  • 1
    Background --accent-red2 — the critical, blocking tone.
  • 2
    Title, Subtitle --text-and-icon-always-light.
  • 3
    Icon --text-and-icon-always-light.

Warning

Weak GPS signal
Your location may be inaccurate
1
2
3
  • 1
    Background --accent-orange2 — a caution the user should notice but that is not blocking.
  • 2
    Title, Subtitle --text-and-icon-always-light.
  • 3
    Icon --text-and-icon-always-light.

Success

Payment received
Your trip is confirmed
1
2
3
  • 1
    Background --accent-green2 — a positive confirmation at screen level.
  • 2
    Title, Subtitle --text-and-icon-always-light.
  • 3
    Icon --text-and-icon-always-light.

RTL is opt-in per instance — dir="rtl" on the root (or .header-alert--rtl). The Content row's horizontal slot order mirrors; the title and subtitle stay centered; the close glyph is directional-neutral and is not mirrored.

RTL

No internet connection
Some features may be unavailable
1
2
  • 1
    End-slot (close) Mirrored to the leading side of the Content row.
  • 2
    Leading-spacer Swaps to the trailing side, keeping the message optically centered.

Anatomy

The root reserves the system status-bar zone at the top; the message sits in the Content row pinned to the bottom. A leading spacer mirrors the close slot so the title / subtitle stay optically centered.

Elements

Title
Subtitle
1
2
3
4
  • 1
    leading-spacer 40 × 40 empty slot — mirrors the end slot to keep the message optically centered. Shown only together with the close control.
  • 2
    title Single line, Heading 4. Required.
  • 3
    subtitle Supporting line, Compact Body. Optional — hide the element when absent.
  • 4
    end-slot (close) 40 × 40 — component-owned close icon button (24 × 24 icon). Optional, off by default.

Layout

All internal spacing uses SP tokens.

Spacing

Title
Subtitle
Title
EndSlot off — StartText spans the full content width
1
2
  • General Top safe zone is reserved for the system panel (status bar) — the component draws no status bar; it only holds the space.var(--sp-s56) — static height without the system panel.var(--sp-s8) — on all sides of the Content row.var(--sp-s0) — gap between the textContainer and the start / end slot.var(--sp-s0) — roundness.Slots are top-aligned inside the var(--sp-s56) container (vertical padding var(--sp-s8)); a 2-line subtitle grows downward, so the start / end slots stay fixed. The container sits below the reserved safe zone.Opt-in via dir="rtl" or .header-alert--rtl. The Content row reverses (end-slot ↔ leading-spacer); title/subtitle stay centered, close glyph is not mirrored.
  • 1
    StartText var(--sp-s4) — title ↔ subtitle gap. Subtitle is optional, hidden by default — the default state is title only.
  • 2
    Leading spacer / end slot var(--sp-s40) × var(--sp-s40) · close icon 24 × 24 inside. The close control is optional, off by default — turn it on to let the user dismiss the banner.

Animation

Reference: motion-rules.md. HeaderAlert enters and leaves off-screen from the top edge — it slides down from behind the status bar (Enter/Default, 250ms) and slides straight back up the moment the close control is released (250ms, exit curve). Only transform is animated. Under prefers-reduced-motion: reduce the tokens resolve to 0ms — the banner appears / leaves instantly.

Motion

No internet connection
Some features may be unavailable
Live: slides in from above → close press → slides straight back up on release, looping
  • 1
    Appear Transforming/Enter/Default — translateY(-100%)→0 in 250ms (slides down from behind the status bar).
  • 2
    Close press → Hide Press feedback on the close button (--ha-pressed / --ha-released); the moment it releases, the exit runs — 0→translateY(-100%) in 250ms (duration.medium1, exit curve), off the top edge.

Usage

Use when a screen-level, blocking or critical state must be announced at the top of the screen, and the message needs to persist until the state resolves or the user dismisses it.

  • 1
    Not for transient messages Informational or auto-dismissing → use Toast / Snackbar.
No internet connection
Some features may be unavailable
✓ Screen-level, blocking state
Saved to favorites
✕ Transient confirmation → use Toast

Accessibility

HeaderAlert is an assertive, screen-level status announcement — exposed as a live region / alert that interrupts the screen reader on appear. Full spec: specs/components/header-alert/header-alert-a11y.md.

Screen reader

No internet connection
Some features may be unavailable
1
2
  • 1
    Message (title + subtitle) Grouped into one node and announced together, assertively, on appear. The leading spacer is decorative — never focused.
  • 2
    Close button Independently focusable, labelled "Dismiss". When close is off, the banner has no focusable element.
  • Contrast
  • 4
    Text on fill --text-and-icon-always-light on the tone's --accent-*2 — verify ≥ 4.5:1 for the shipped values.