Use notifications for system-level messages and status updates. When feedback belongs directly to a field, control, or focused task area, keep it closer to that context instead.
When to use
Use notifications when
- Communicating system events, errors, or status changes users need to know about
- Providing asynchronous feedback that is not tied to a specific field or control
- Stacking multiple independent alerts in a fixed portal without blocking content
- Showing updates that users should notice but do not need to answer immediately
Do not use notifications when
- The feedback is a direct result of a user action and belongs near that action
- The message is so critical that users must not be able to miss or dismiss it
- The text is too long to scan quickly
- The message needs detailed explanation rather than a short, scannable summary
Patterns
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Container | The outer surface that groups the notification content into one message block |
| 2 | Icon | A semantic icon that communicates the notification type at a glance |
| 3 | Label | The primary message in the notification (default slot) |
| 4 | Close button | Optional control that allows the user to dismiss the notification manually |
| 5 | Description | Optional supporting text or links shown in the body slot |
| 6 | CTA buttons | Optional action buttons shown in the footer slot |
Design guidelines
Choose the notification treatment that matches the urgency of the message without interrupting the current task.Choose the purpose
Start by deciding whether the message is informational, successful, cautionary, or error-related. That determines the right
type.Decide whether actions are needed
Add footer actions only when users genuinely need a next step such as retrying, reviewing, or navigating.
If you use
auto-dismiss, make sure the timeout gives users enough time to read the content and does not remove important information too quickly.Usage
Default
Use the defaultinfo notification for standard messages and updates.
Options
Semantic types
Use semantictype values to communicate severity and intent clearly.
Custom icon
Use theicon slot to replace the default type icon with a custom bq-icon.
Stacked notifications
Use thetoast() method to render notifications in a fixed-position portal that stacks multiple notifications vertically outside the normal document flow. The component creates and reuses a .bq-notification-portal element attached to document.body, and BEEQ global styles position that portal for you.
In framework apps, prefer a framework-owned portal or stack when you want the notification lifecycle to stay declarative.
Best practices
DoPosition notifications at the edges of the screen so they do not block the main content.
Don’tDo not position notifications in the center of the screen where they compete with the main task.
DoKeep messages concise and direct, and lead with the most important information.
Don’tDo not use long descriptions in notifications because they reduce scanability.
DoUse the correct
type so the icon and visual treatment reinforce the message severity.Don’tDo not rely on custom colors or ambiguous language to communicate urgency.
DoProvide a close button or a thoughtful auto-dismiss timeout so users can dismiss notifications predictably.
Don’tDo not use all-caps or unnecessary typographic emphasis in notification copy.
Accessibility
- Built-in alert role — the component applies
role="alert"to the notification host element, which implicitly carriesaria-live="assertive". Assistive technology announces new notifications immediately when they appear. - Visibility tied to
open— the host also receivesaria-hidden="true"whenopenisfalse, removing it from the accessibility tree when not visible. - Color alone is not enough: the icon and message text should work together so users who cannot perceive color still understand the notification.
- Keep interactive elements reachable: users must be able to tab to the close button, links, and footer actions and activate them with the keyboard.
- Use considerate auto-dismiss timing: if
auto-dismissis enabled, give users enough time to read the content before it disappears. - Do not steal focus: stacked notifications are non-modal and should not move focus unexpectedly away from the current task.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
autoDismiss | auto-dismiss | If true, the notification closes automatically after time milliseconds | boolean | undefined |
border | border | Border radius of the notification component | "none" | "xs2" | "xs" | "s" | "m" | "l" | "full" | "s" |
disableClose | disable-close | If true, the close button is not shown | boolean | undefined |
hideIcon | hide-icon | If true, the type icon is not shown | boolean | undefined |
open | open | If true, the notification is visible | boolean | undefined |
time | time | Duration in milliseconds before auto-dismissal. Only valid when auto-dismiss is true | number | 3000 |
type | type | The semantic type of the notification | "error" | "info" | "neutral" | "success" | "warning" | "info" |
Events
| Event | Description | Type |
|---|---|---|
bqAfterClose | Fired after the notification finishes closing | CustomEvent<void> |
bqAfterOpen | Fired after the notification finishes opening | CustomEvent<void> |
bqHide | Fired when the notification is about to hide | CustomEvent<HTMLBqNotificationElement> |
bqShow | Fired when the notification is about to show | CustomEvent<HTMLBqNotificationElement> |
- In React, prefix events with
on:onBqHide,onBqShow,onBqAfterClose,onBqAfterOpen. - In Angular, use the event binding syntax:
(bqHide),(bqShow),(bqAfterClose),(bqAfterOpen). - In Vue, use the
@shorthand:@bqHide,@bqShow,@bqAfterClose,@bqAfterOpen.
Methods
| Method | Description | Returns |
|---|---|---|
hide() | Hides the notification | Promise<void> |
show() | Shows the notification | Promise<void> |
toast() | Renders the notification in the fixed-position stacking portal | Promise<void> |
Slots
| Slot | Description |
|---|---|
| (default) | The notification title content |
body | The notification description content |
btn-close | Replaces the default close button content |
footer | The notification footer content |
icon | Replaces the default type icon with a custom bq-icon |
Shadow parts
| Part | Description |
|---|---|
base | The <div> container of the predefined bq-icon |
body | The <div> wrapping the notification description content |
btn-close | The bq-button used to close the notification |
content | The <div> wrapping all notification content |
footer | The <div> wrapping the notification footer content |
icon | The <bq-icon> element rendered based on the notification type |
icon-outline | The <div> wrapping the icon element |
main | The <div> wrapping the notification main content |
svg | The <svg> element of the predefined bq-icon |
title | The <div> wrapping the notification title content |
wrapper | The outermost wrapper <div> inside the shadow DOM |
CSS custom properties
Resources
Interactive playground
Explore all notification types and states in the Storybook playground.
Source code
Browse the full source code, including implementation, tests, and styles.