Skip to main content
BEEQ Toast component overview

Toast component overview

Toasts are brief, non-blocking status messages that appear temporarily to confirm an action, report a lightweight issue, or indicate background progress. They keep people informed without pulling them out of their current flow.
Use a toast for lightweight feedback that does not require a response. If the message is longer, needs actions, or must remain visible until dismissed, prefer a notification or dialog.

​
When to use

Use toasts when
  • Confirming that a user-triggered action completed successfully
  • Reporting a lightweight issue that does not block the current task
  • Indicating short-lived background activity such as syncing or loading
  • Keeping feedback close to the moment of interaction without interrupting the page

Do not use toasts when
  • The message is critical and must not be missed
  • The user needs to choose an action before continuing
  • The content is too long to scan in a few seconds
  • Multiple concurrent messages would compete for attention

​
Patterns

Informational toast

Informational toasts provide users with relevant information or guidance about a particular action or feature.

Error toast

Error toasts inform the user about issues that occur during user interaction and provide guidance on how to resolve them.

Loading toast

Loading toasts indicate to users that a process is underway, such as data retrieval or content loading.

Success toast

Success toasts confirm to users that an action has been completed successfully.

Warning toast

Warning toasts warn users about potential risks or issues that require attention.

Custom toast

Custom toasts are personalized messages tailored to specific user interactions or application contexts.

​
Anatomy

BEEQ Toast component anatomy

Toast component anatomy

Each toast contains a compact message and, by default, a semantic icon that helps users understand the status instantly. Toasts should always include a clear label, and that label should be paired with the icon that best matches the message meaning.
Toasts use a standard size intended to work across most interfaces. Prefer the default sizing and spacing so messages stay compact, readable, and visually consistent.

​
Design guidelines

Use toast messages carefully so they stay brief, noticeable, and easy to understand without interrupting the current task.
1

Be concise

Keep the message short and direct. Limit the content to one or two brief sentences.
2

Provide context

Include enough context for users to understand why the toast appeared and what happened.
3

Use sentence case

Write toast text in sentence case instead of using capitalization to force emphasis.
Show one toast at a time when possible. If several events happen close together, prefer a controlled queue or a tightly managed stack so messages remain readable and do not overlap bottom navigation, floating action buttons, or other critical controls.

​
Usage

​
Default

Use the built-in type values to communicate the nature of the message quickly. Keep the text concise and let the icon and color carry the status cue. info is the default type, while success, alert, error, and loading cover the most common toast states.

​
Options

​
Custom icon

Use type="custom" when you need a branded or domain-specific status cue. Replace the default icon through the icon slot.

​
Portal placement and stacking

Use a dedicated toast container when you want the stacking behavior to be explicit in the markup. This example keeps the stack at the top center and appends each new toast into the same container, while keeping the visible documentation focused on the structure rather than the implementation details.

​
Best practices

DoKeep toast copy short, direct, and written in sentence case.

Don’tDon’t use a toast for long explanations, multi-step guidance, or anything users may need to revisit later.

DoUse the correct semantic type so icon and color reinforce the meaning immediately.

Don’tDon’t flood the interface with many simultaneous toasts. If several events occur, queue or stack them in a controlled order.

DoPlace viewport toasts where they do not cover bottom navigation, floating actions, or other critical controls.

Don’tDon’t rely on a toast alone for critical errors or irreversible outcomes that require acknowledgment.

DoSet a long enough time for users who may need more seconds to read the message, especially if it contains an error explanation.

Don’tDo not auto-dismiss a toast that users may need to act on or reference. Use a notification or dialog for persistent messages instead.

​
Accessibility

  • Announced as status - the component uses role="status", so the message should make sense when read aloud without surrounding visual context.
  • Not color-only - do not rely on icon color alone to communicate meaning. The message text itself should state what happened clearly.
  • Allow enough reading time - increase time for longer messages, and avoid auto-dismissing content people may need more than a few seconds to read.
  • Do not steal focus - toasts are non-modal status messages and should not interrupt the current keyboard focus or workflow.
  • Use a stronger pattern when needed - if the message requires action, contains links, or must remain available, use a persistent notification or dialog instead.

​
API reference

​
Properties

​
Events

  • In React, prefix events with on: onBqHide, onBqShow.
  • In Angular, use the event binding syntax: (bqHide), (bqShow).
  • In Vue, use the @ shorthand: @bqHide, @bqShow.
  • preventDefault() is supported on both events. Calling it cancels the default show or hide behavior while still letting your event handler run.

​
Methods

​
Slots

​
Shadow parts

​
CSS custom properties

Learn more about styling with shadow parts and CSS custom properties.

​
Resources

Interactive playground

Explore toast types, placement, and stacking behavior in Storybook.

Source code

Browse the component implementation, styles, and tests on GitHub.