When to use
Use alerts when
- You need to clearly and concisely convey important information
- A message applies to a page, card, section, or system-level state
- Users need feedback after submitting data, changing permissions, or completing an action
- Users need to know about errors, warnings, maintenance, upgrades, or time-sensitive tasks
Do not use alerts when
- The alert would disrupt a critical task
- The message overlaps essential content or important interface controls
- Its presence could confuse users or compete with a more relevant inline message
- A toast, notification, or field-level validation message would be more precise
Patterns
Alerts can be used at different scopes, depending on what the message affects.Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Container | The alert surface that groups the message, icon, title, and actions |
| 2 | Icon | Status icon, or a custom icon when the alert uses the default type |
| 3 | Title | The alert title content in the default slot |
| 4 | Close button | Dismisses the alert unless disable-close is set |
| 5 | Description | Optional supporting content in the body slot |
| 6 | CTA button | Optional action content in the footer slot |
Design guidelines
Types
Set
border to match the surface where the alert appears. Use the same radius scale as the surrounding layout.Usage
Default
Use thedefault variant for general-purpose alerts. It lets you customize the bq-icon for messages with no associated severity.
Info
Use theinfo variant when users need additional, non-critical information. It works well for context that helps users understand a state without requiring immediate action.
Success
Use thesuccess variant to notify users about successful actions or positive outcomes. This type of alert is ideal for celebrating achievements, completed processes, or any operation that concludes successfully.
Warning
Use thewarning variant to indicate potential issues or actions that users should approach with caution. This alert helps draw attention to situations that require careful consideration but may not be critical.
Error
Use theerror variant for issues that require immediate attention. It works best for problems that block the task or prevent a successful outcome.
Options
Sticky
Use thesticky attribute for persistent alerts that remain visible until users dismiss them. Sticky alerts work well for ongoing information that needs prolonged attention, such as system updates or maintenance notices.
Auto-dismiss
Setauto-dismiss to hide the alert automatically after a delay. Use time to override the default 3000 ms. Set a minimum of 8000 ms for alerts with meaningful content so users have enough time to read the message.
Best practices
DoPlace alerts close to the content or workflow they affect.
Don’tDo not place alerts where they hide controls or interrupt a critical task.
DoWrite a short title that explains the state, then add body text only when users need context.
Don’tDo not use long paragraphs or unrelated links inside an alert.
DoGive users enough time to read auto-dismiss alerts and keep important messages dismissible by intent.
Don’tDo not auto-dismiss alerts that contain errors, required actions, or legal information.
DoMatch the alert type, icon, and action style to the severity of the message.
Don’tDo not mix severity colors or custom icons in ways that make the alert harder to scan.
Accessibility
- The host uses
role="alert"so assistive technologies announce the message when it appears. - The host sets
aria-hiddenfrom theopenstate, keeping hidden alerts out of the accessibility tree. - The default close button has the accessible label “Close alert.”
typeprovides visual intent and a matching predefined status icon forinfo,success,warning, anderror.- Provide a concise title in the default slot and supporting details in the
bodyslot when users need more context. - The built-in type tokens (
info,success,warning,error) meet WCAG AA color-contrast requirements in both light and dark themes. Verify contrast manually when using custom colors via CSS variables. - All interactive elements inside the alert — the close button, footer actions, and body links — must be reachable via
Taband have a visible focus indicator. - Set
timeto a minimum of 8000 ms forauto-dismissalerts. Do not auto-dismiss while the user has keyboard focus or hover inside the alert. - When
stickyis enabled, keep the page focus order logical so keyboard users can still reach the affected content.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
autoDismiss | auto-dismiss | If true, the alert will automatically hide after the specified amount of time | boolean | false |
border | border | The corner radius of the alert component | 'none' | 'xs2' | 'xs' | 's' | 'm' | 'l' | 'full' | 's' |
disableClose | disable-close | If true, the close button at the top right of the alert will not be shown | boolean | false |
hideIcon | hide-icon | If true, the alert icon will not be shown | boolean | false |
open | open | If true, the alert will be shown | boolean | false |
sticky | sticky | If true, the alert remains fixed at the top of the page, occupying the full viewport width | boolean | false |
time | time | The length of time, in milliseconds, after which the alert closes itself. Only valid when auto-dismiss is set | number | 3000 |
type | type | Type of alert | 'default' | 'error' | 'info' | 'success' | 'warning' | 'default' |
Events
| Event | Description | Type |
|---|---|---|
bqHide | Fires when the alert starts to hide | CustomEvent<any> |
bqShow | Fires when the alert starts to show | CustomEvent<any> |
bqAfterHide | Fires after the alert has been hidden | CustomEvent<any> |
bqAfterShow | Fires after the alert has been shown | CustomEvent<any> |
- In React, prefix events with
on:onBqShow,onBqHide,onBqAfterShow,onBqAfterHide. - In Angular, use the event binding syntax:
(bqShow),(bqHide),(bqAfterShow),(bqAfterHide). - In Vue, use the
@shorthand:@bqShow,@bqHide,@bqAfterShow,@bqAfterHide.
Methods
| Method | Description | Type |
|---|---|---|
show() | Shows the alert component | Promise<void> |
hide() | Hides the alert component | Promise<void> |
Slots
| Slot | Description |
|---|---|
| (default) | The alert title content |
body | The alert description content |
footer | The alert footer content |
icon | Custom icon content. Status types render predefined icons when this slot is empty |
btn-close | Custom close button content |
Shadow parts
| Part | Description |
|---|---|
base | The <div> container of the predefined bq-icon component |
body | The container <div> that wraps the alert description content |
btn-close | The native button of the bq-button used to close the alert |
content | The container <div> that wraps all alert content: title, description, and footer |
footer | The container <div> that wraps the alert footer content |
icon | The <bq-icon> element used to render a predefined icon based on the alert type |
icon-outline | The container <div> that wraps the icon element |
main | The container <div> that wraps the alert main content |
svg | The <svg> element of the predefined bq-icon component |
title | The container <div> that wraps the alert title content |
wrapper | The wrapper container <div> inside the shadow DOM |
CSS custom properties
Resources
Use Storybook to test behavior and states interactively, or review the source if you need implementation details.Interactive playground
Explore all alert configurations in Storybook
Source code
View the component source on GitHub