Alert
Alerts are used to convey important, and often time-sensitive, contextual feedback messages to users regarding actions or system responses. They can communicate success, warnings, errors, or general information that requires the user's attention. Alerts are designed to be noticeable without disrupting the entire user flow.
When to use
- To provide feedback after a user action (e.g., form submission, save, delete)
- To communicate system status (e.g., maintenance, outage, degraded service)
- To display validation errors or warnings
- To highlight important information that requires user attention
When not to use
- For transient notifications that auto-dismiss (use Toast instead)
- For blocking user actions that require confirmation (use Modal instead)
- For inline field-level validation messages (use form validation feedback)
Variants
The component supports 8 color variants across multiple structural combinations.
Normal
Simple single-line alerts for brief messages.
Dismissible
Alerts can be configured to include a close button, allowing users to dismiss them once read or addressed.
With icon
Including an icon that matches the alert's context (e.g., checkmark, warning triangle, info circle) is highly recommended to visually reinforce the message type. Pass icon as true to use the default icon for each variant, or pass a Bootstrap icon class for a custom icon.
Dismissible with icon
Dismissible with custom close button
This gallery shows the custom Close button across all eight color variants. Apply q-alert__custom-close to style the button with the alert's colors and Figma-matched dimensions. The close slot replaces the built-in control, so its handler manages visibility; this example updates the parent state directly and does not emit the component's close, update:modelValue, or dismissed events.
Additional content
Use the title prop and the default slot to create alerts with a heading and extended content.
Additional content dismissible
Additional content with icon
Full combination (icon + title + custom close button)
Custom icon
You can pass a specific Bootstrap icon class to the icon prop instead of true.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
variant | string | "primary" | Color variant: primary, secondary, success, danger, warning, info, light, dark |
title | string | undefined | Bold heading text for additional content alerts |
icon | string | boolean | undefined | Bootstrap icon class, or true for automatic icon based on variant |
dismissible | boolean | false | Show close button to dismiss the alert |
closeLabel | string | "Close" | Accessible label for the built-in close button |
closeContent | string | "" | Optional content inside the built-in close button |
modelValue | boolean | true | Controls visibility (supports v-model) |
Events
| Event | Payload | Description |
|---|---|---|
close | Event | Emitted by the built-in close button before dismissal. Call event.preventDefault() in the listener to keep the alert open. |
update:modelValue | boolean | Emitted by the built-in close button when the alert is dismissed (value: false) |
dismissed | — | Emitted by the built-in close button when the alert is dismissed |
Slots
| Slot | Description |
|---|---|
default | Alert content (text, paragraphs, links) |
icon | Override the default icon rendering |
close | When dismissible is true, replace the built-in close button with a custom control |
Accessibility
- Uses
role="alert"for screen reader announcements - Built-in close button includes
aria-label(customizable viacloseLabelprop); custom close controls must provide their own accessible name - Color is not the only means of conveying information — icons reinforce the message type
- Text contrast ratios meet WCAG AA requirements through design token colors