Alert
Overview
A callout that surfaces important, time-sensitive information — warnings, errors, or confirmations — near the content it refers to. SAlert combines an AlertRoot/AlertTitle/AlertDescription/AlertClose family of Aria primitives (zero styles) with the alertVariants style recipe (6 slots, 8 colors × 5 variants × 6 sizes).
Use it for inline feedback that must not be missed. Prefer toast for transient, global notifications and dialog for blocking confirmations. For a banner-style full-width variant, track the roadmap Banner item.
Usage
Features
- 🧩 Aria/styled split —
AlertCompactaggregates the primitives and composes the default icon/title/description/close;SAlertonly injects styles and forwards slots/events - 🏷️ Title + description —
title/descriptionprops or the matching slots - ❌ Closable —
closablerenders a close<button>(localizedaria-label) driven byv-model:open - 🎨 8 colors —
ThemeColorvalues (primary/destructive/success/warning/info/carbon/secondary/accent) - 🖌️ 5 variants —
solid/pure/outline/soft/ghost - 📐 6 sizes — xs–2xl
size - 🖼️ Leading icon —
iconprop or theleadingslot - ♿ Accessible — the close control is a real
<button>with a localizedaria-label;axe-corereports zero violations
Component family
SAlert(styled) — the entry wrapper;alertVariantsrecipe with dynamic slot forwardingAlertRoot(Aria) — the container; ownsopenviauseControllableStateandprovideAlertRootContextAlertContent(Aria) — the content area hosting title/descriptionAlertTitle(Aria) — the titleAlertDescription(Aria) — the descriptionAlertClose(Aria) — the close<button>; localizedaria-label, emitscloseand togglesopenAlertCompact(Aria) — the aggregated composite; composes icon/title/description/close and exposes the slots
Demos
Basic
100%
Info
This is an info alert
Slot
100%
Flighting !!!
API
Aria Layer
7Alert
15 Props2 Emits6 Slots
Props
| Prop | Type | Default | Description |
|---|---|---|---|
class | ClassValue | — | root class |
size | ThemeSize | — | Visual size of the component. |
color | ThemeColor | — | Theme color of the component. |
variant | AlertVariant | — | Visual variant of the component. |
ui | Partial<AlertUi> | — | Per-slot class overrides for the component. |
title | string | — | Title text rendered by the component. |
description | string | — | Description text rendered by the component. |
icon | IconValue | — | Icon rendered by the component. |
closable | boolean | — | Whether the component can be closed. |
contentProps | AlertContentProps | — | Properties forwarded to the content element. |
titleProps | AlertTitleProps | — | Properties forwarded to the title element. |
descriptionProps | AlertDescriptionProps | — | Properties forwarded to the description element. |
closeProps | AlertCloseProps | — | Properties forwarded to the close element. |
open | boolean | true | The controlled open state of the alert. Can be bound with `v-model:open`. |
role | 'alert' | 'status' | 'alert' | The ARIA live region role of the alert. `role="alert"` implies an
assertive live region (interrupting), while `role="status"` implies a
polite one (non-interrupting). |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:open | boolean | Emitted when the open changes. |
close | PointerEvent | Emitted when the close button is clicked. |
Slots
| Slot Name | Parameters | Description |
|---|---|---|
default | — | Custom content for the default slot. |
leading | — | Custom content for the leading slot. |
title | — | Custom content for the title slot. |
description | — | Custom content for the description slot. |
trailing | — | Custom content for the trailing slot. |
close | — | Custom content for the close slot. |
AlertClose
4 Props1 Emits
Props
| Prop | Type | Default | Description |
|---|---|---|---|
type | ButtonType | 'button' | The type of the button element. Can be one of 'button', 'submit', or 'reset'. |
disabled | boolean | — | Whether the component is disabled. |
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
close | PointerEvent | Emitted when the close button is clicked. |
AlertCompact
10 Props2 Emits6 Slots
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Title text rendered by the component. |
description | string | — | Description text rendered by the component. |
icon | IconValue | — | Icon rendered by the component. |
closable | boolean | — | Whether the component can be closed. |
contentProps | AlertContentProps | — | Properties forwarded to the content element. |
titleProps | AlertTitleProps | — | Properties forwarded to the title element. |
descriptionProps | AlertDescriptionProps | — | Properties forwarded to the description element. |
closeProps | AlertCloseProps | — | Properties forwarded to the close element. |
open | boolean | true | The controlled open state of the alert. Can be bound with `v-model:open`. |
role | 'alert' | 'status' | 'alert' | The ARIA live region role of the alert. `role="alert"` implies an
assertive live region (interrupting), while `role="status"` implies a
polite one (non-interrupting). |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:open | boolean | Emitted when the open changes. |
close | PointerEvent | Emitted when the close button is clicked. |
Slots
| Slot Name | Parameters | Description |
|---|---|---|
default | — | Custom content for the default slot. |
leading | — | Custom content for the leading slot. |
title | — | Custom content for the title slot. |
description | — | Custom content for the description slot. |
trailing | — | Custom content for the trailing slot. |
close | — | Custom content for the close slot. |
AlertContent
AlertDescription
AlertRoot
2 Props1 Emits
Props
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | true | The controlled open state of the alert. Can be bound with `v-model:open`. |
role | 'alert' | 'status' | 'alert' | The ARIA live region role of the alert. `role="alert"` implies an
assertive live region (interrupting), while `role="status"` implies a
polite one (non-interrupting). |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:open | boolean | Emitted when the open changes. |
AlertTitle
Notes
Architecture and benchmark differences
AlertCompact owns the icon/title/description/close composition while every primitive stays style-free and only the UI wrapper injects the alertVariants classes. This mirrors shadcn/ui’s headless/styled split, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a single styled alert with type/closable/showIcon props. VeanUI exposes the full per-slot *Props channels and a size scale the single-package libraries generally omit, and localizes the close button’s aria-label (via alert.close) instead of relying on a plain × glyph.
| Capability | VeanUI | shadcn/ui | Ant Design Alert | Element Plus Alert | Mantine Alert | Naive UI Alert |
|---|---|---|---|---|---|---|
| Aria/styled split | ✅ | ✅ | — | — | — | — |
| Title + description | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Closable | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| Leading icon | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| Variants (solid/soft/ghost) | ✅ | ✅ | — | — | — | — |
| Colors (8) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Sizes (6) | ✅ | — | — | — | — | — |
| Localized close label | ✅ | — | — | ✅ | — | — |
— = unsupported or a different interaction model.
Cautions
- The close button’s
aria-labelis localized fromalert.close(e.g.Close alert). Override it viaaria-labelonSAlertor a customcloseslot. opendefaults totrue;closableshows the close button. Bindopenwithv-modelto control dismissal.variant="solid"swaps text to the color’s foreground;soft/ghosttint the background with a translucent color.- The
iconleading graphic is decorative; the title/description carry the message content. Alertis a static callout — it does not set a live/alertroleor auto-dismiss; usetoastfor transient notifications.
Roadmap
A full-width Banner variant is tracked in docs/roadmap/README.md (P2).
FAQ
How do I show a title and description?
Pass title/description props (or the matching slots):
<SAlert color="warning" title="Heads up" description="Your session will expire soon." />How do I make an alert closable?
Set closable and bind open with v-model:
<SAlert v-model:open="open" closable title="Dismiss me" />How do I change the color and variant?
Use color (8 values) and variant (solid/pure/outline/soft/ghost):
<SAlert color="success" variant="soft" title="Saved" description="All changes are stored." />How do I add an icon?
Use the icon prop (via ConfigProvider iconRender) or the leading slot:
<SAlert icon="lucide:info" title="Information" description="Read the docs." />How do I customize the close control?
Use the close slot and read the close behavior from it (or provide your own aria-label):
<SAlert v-model:open="open" closable title="Custom close">
<template #close>
<button type="button" aria-label="Dismiss" @click="open = false">×</button>
</template>
</SAlert>