Skip to main content
BEEQ Notification component overview

Notification component overview

Notifications inform people about significant events, status changes, or updates that need their awareness without requiring an immediate response. They appear at the edge of the interface, stack gracefully when multiple are present, and dismiss automatically or on demand.
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

BEEQ Notification component anatomy

Notification component anatomy

A notification is composed of a container, an icon, a label, an optional close button, an optional description, and optional call-to-action buttons.

​
Design guidelines

Choose the notification treatment that matches the urgency of the message without interrupting the current task.
1

Choose the purpose

Start by deciding whether the message is informational, successful, cautionary, or error-related. That determines the right type.
2

Decide whether actions are needed

Add footer actions only when users genuinely need a next step such as retrying, reviewing, or navigating.
3

Choose placement

Use inline open notifications for contained layouts. Use toast() for stacked, portal-based notifications outside the document flow.
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 default info notification for standard messages and updates.
Notifications take up the full width of their parent container. Wrap them in a container with a max-width if you need a more constrained layout.

​
Options

​
Semantic types

Use semantic type values to communicate severity and intent clearly.

​
Custom icon

Use the icon slot to replace the default type icon with a custom bq-icon.

​
Stacked notifications

Use the toast() 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 carries aria-live="assertive". Assistive technology announces new notifications immediately when they appear.
  • Visibility tied to open — the host also receives aria-hidden="true" when open is false, 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-dismiss is 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

​
Events

  • 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

​
Slots

​
Shadow parts

​
CSS custom properties

Learn more about styling with shadow parts and 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.