Alert

An inline message with a status color and icon — info, success, warning, or critical; inline, filled or as a full-width banner.

Last updated

Heads up

A new version of this page is available.

Show code
<Alert color="primary" title="Heads up">
A new version of this page is available.
</Alert>

Add

npx @ava-ui/apogee add alert

Uses @lucide/astro (Info, CircleCheck, TriangleAlert, CircleAlert) for the per-variant icon.

Usage

---
import Alert from '@/components/apogee/Alert/Alert.astro'
---
<Alert color="positive" title="Saved">Your changes were saved.</Alert>

API

@composable — exposed to Content Editors in AVA. Any other attribute (e.g. role, aria-live, id) passes through.

Prop Type Default Description
color 'primary' | 'neutral' | 'critical' | 'positive' | 'warning' 'neutral' The hue.
variant 'faded' | 'solid' | 'banner' 'faded' Tinted (default), filled, or a full-width strip with a bottom rule and the content in a centred column.
featured boolean false Puts the icon in a FeaturedIcon tile.
title string — Optional bold heading above the message.
inline boolean false Hides the icon column.
role string 'alert' for critical and warning Live-region role. Critical and warning alerts announce themselves; pass role (or role="status") to override.
class string — Extra classes, appended last.

Slots: default for the message, actions for buttons under it.

Colors × variants

Every color, each with its fixed icon, tinted and filled:

Note

A neutral callout.

Info

Informational message.

Success

Action completed.

Note

A neutral callout.

Info

Informational message.

Success

Action completed.
Show code
<Alert color="neutral" title="Note">A neutral callout.</Alert>
<Alert color="primary" title="Info">Informational message.</Alert>
<Alert color="positive" title="Success">Action completed.</Alert>
<Alert color="warning" title="Warning">Check this before continuing.</Alert>
<Alert color="critical" title="Error">Something went wrong.</Alert>
<Alert variant="solid" color="neutral" title="Note">A neutral callout.</Alert>
<Alert variant="solid" color="primary" title="Info">Informational message.</Alert>
<Alert variant="solid" color="positive" title="Success">Action completed.</Alert>
<Alert variant="solid" color="warning" title="Warning">Check this before continuing.</Alert>
<Alert variant="solid" color="critical" title="Error">Something went wrong.</Alert>

A banner spans its container with a rule at the bottom; its content sits in a centred column, the icon hides on phones and the actions move to the end from md. Pin it to the bottom on phones with class="max-md:sticky max-md:bottom-0".

New version available

Reload to get the latest fixes and the new export panel.

Payment received

Your invoice for October is paid.
Show code
<Alert variant="banner" color="primary" title="New version available">
Reload to get the latest fixes.
<Button slot="actions" size="small">Reload</Button>
</Alert>
<Alert featured color="positive" title="Payment received">Your invoice is paid.</Alert>

Dismissal is a Dismissible around the alert: <Dismissible align="top"><Alert class="pe-10">…</Alert></Dismissible>.

Icon slot and roles

A custom icon replaces the colour’s default; critical and warning get role="alert" automatically.

New release

Version 0.4 is out.

Note

No role: a static callout.
Show code
<Alert color="primary" title="New release"><Rocket slot="icon" />Version 0.4 is out.</Alert>
<Alert color="critical" title="Payment failed">Announced as an alert.</Alert>
<Alert color="primary" title="Note">No role: a static callout.</Alert>

States

Alert is static — no hover/focus/disabled states. The one behavioral distinction is static (page) vs dynamic (result of an action), which changes the ARIA role you pass in, not the markup:

Show code
<Alert color="warning" title="Limited availability">
Only 2 left in stock.
</Alert>
<Alert color="critical" title="Couldn't save" role="alert">
Check the highlighted fields and try again.
</Alert>

Examples

Without a title — the message alone takes the primary text color:

No title, just a message.
Show code
<Alert color="primary">No title, just a message.</Alert>

With a link in the body:

<Alert color="warning" title="Update required">
  Your plan expires soon. <a href="/billing" class="underline">Renew now</a>.
</Alert>

Accessibility

  • Icons are aria-hidden — the status is conveyed by the adjacent text, not color/icon alone.
  • Critical and warning alerts get role="alert" by default, so they are announced when inserted. Other colours have no role: a static callout needs none. Pass role ("status", or "" for none) to override.

Tokens

Token Used for
--background-{hue}-faded / --border-{hue}-faded Surface and border of the faded variant, per color
--foreground-{hue} Icon of the faded variant
--background-{hue} / --on-{hue} Surface and text of the solid variant
--foreground-neutral Title text
--foreground-neutral-faded Body text (when a title is present)

Do / Don’t

  • Do match the variant to the message’s actual severity — don’t use critical for a neutral notice.
  • Do keep the title short; put detail in the body.
  • Don’t stack more than one Alert for the same event — pick the highest-severity one.
  • Don’t use critical for destructive-action confirmation — that’s a dialog’s job, not an inline alert’s.

Content

  • Title: 2–5 words, sentence case, no ending period, states the outcome (“Couldn’t save”, not “Error”).
  • Body: one or two short sentences. Say what happened and, for warnings and critical alerts, what to do next.

Related

ToastA transient notification, fired imperatively from anywhere on the page.
DismissibleWrap anything with a close button, with an optional auto-dismiss timeout.
EmptyStateA centered placeholder for empty views — no results, first run, a cleared list.