Announcement
Global site-wide notification displayed at the top of the page above the header. Used to communicate service-wide status, maintenance windows, or urgent information that applies to every page. Distinct from message (action feedback) and callout (editorial emphasis).
Usage
When to use
- Site-wide status: outages, maintenance windows, service disruptions
- Legal or compliance notices required on every page (cookies, regulatory banners)
- Urgent, time-sensitive information applying to the whole site
When not to use
- For per-page feedback after a user action - use
messageinstead - For editorial emphasis within content - use
calloutinstead
Do
- Keep the message short and scannable
- Pair color with an icon and plain text to communicate status
- Provide a dismiss control for non-critical announcements
Don't
- Stack multiple announcements - show one at a time
- Rely on color alone to communicate severity
- Make critical legal notices dismissible
API
Slots
| Slot | Required | Description |
|---|---|---|
content | Yes | Body text content. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
has_close | boolean | - | Whether to show a dismiss button. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.info | Intent | - | Informational message. |
.warning | Intent | - | Warning or caution. |
.danger | Intent | - | Error, destructive, or critical. |
.success | Intent | - | Confirmation or completion. |
.sticky | Position | - | Pins the component to a viewport edge while scrolling. |
.animated | Motion | Yes | Honors the animations option. |
.still | Motion | - | Forces motion off regardless of the option. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-announcement | Consumer | - | On a dismissible announcement, marks it as the root the dismiss behavior binds to. Rendered when has_close is set. |
data-announcements | Consumer | - | On the wrapper that hosts endpoint-fetched announcements, marks it as the injection target. |
data-close | Consumer | - | On a descendant button, marks it as the announcement dismiss trigger consumed by the close utility. |
data-announcement-endpoint | Consumer | - | On the announcements container, a URL that returns a JSON array of { id, message } records to inject above the user content. |
data-announcement-id | Consumer | - | On an API-injected announcement fetched from the endpoint, the per-record identifier used to persist its dismissed state across reloads. Statically rendered announcements persist dismissal by a hash of their content instead. |
Events
| Event | Direction | Description |
|---|---|---|
close-dismiss | Listens | Listened on each announcement. Persists the dismissed state and removes the announcement element when received. |
Examples
Info
Neutral informational announcement with dismiss control.
Success
Success variant for a resolved incident or a restored service.
Warning
Warning variant for non-critical service advisories.
Sticky
Announcement with fixed positioning that stays visible on scroll.
Danger
Danger variant for a critical advisory, rendered without the dismiss control so the message cannot be cleared.
Dismiss
Dismissal is stored under a hash of the content, so the announcement stays hidden until the content changes. The restore control clears that state and renders it again.
JS API
Announcements fetched from an endpoint rather than authored in markup. Switching the endpoint changes the content, which resets the dismissed state and brings the banner back.
Accessibility
- WCAG 2.2 AA
- Urgent, time-sensitive messages must be announced to assistive tech automatically.
- Informational messages must be exposed as status updates without interrupting the user.
- The dismiss control must be keyboard reachable and have an accessible name.
- Status must be communicated via icon and text, not color alone.
- Color contrast must meet AA for each status variant.
Progressive enhancement
- No JS: the announcement renders, is readable, and cannot be dismissed.
- With JS: dismiss control removes the announcement; dismissed state is persisted and is content-aware - if the announcement content changes, the dismissed state resets and the announcement reappears.
- How to enable: include the announcement JS enhancement