Skip to main content
BEEQ Alert component overview

Alert component overview

Alert is a lightweight message surface for conveying status, progress, or required next steps in a clear and consistent way.

​
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

BEEQ Alert component anatomy

Alert component anatomy

​
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 the default variant for general-purpose alerts. It lets you customize the bq-icon for messages with no associated severity.
Set open to show the alert. Use show() and hide() when visibility is controlled programmatically.
Alert fills the width of its parent container.

​
Info

Use the info 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 the success 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 the warning 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 the error variant for issues that require immediate attention. It works best for problems that block the task or prevent a successful outcome.

​
Options

​
Sticky

Use the sticky 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.
Sticky alerts support every alert type: default, success, error, warning, and info.
Sticky alerts use a preset layout with the alert text centered at the top of the screen.

​
Auto-dismiss

Set auto-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.
Do not use auto-dismiss for alerts that contain errors, required actions, or legal information.

​
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-hidden from the open state, keeping hidden alerts out of the accessibility tree.
  • The default close button has the accessible label “Close alert.”
  • type provides visual intent and a matching predefined status icon for info, success, warning, and error.
  • Provide a concise title in the default slot and supporting details in the body slot 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 Tab and have a visible focus indicator.
  • Set time to a minimum of 8000 ms for auto-dismiss alerts. Do not auto-dismiss while the user has keyboard focus or hover inside the alert.
  • When sticky is enabled, keep the page focus order logical so keyboard users can still reach the affected content.

​
API reference

​
Properties

​
Events

  • 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

​
Slots

​
Shadow parts

​
CSS custom properties

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