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
| Part | Element | Description |
|---|---|---|
| 1 | Container | The surface that groups the feedback message into one compact unit |
| 2 | Icon | A semantic icon that reinforces the toast type at a glance |
| 3 | Label | The short message describing what happened or what is happening |
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.Provide context
Include enough context for users to understand why the toast appeared and what happened.
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-intype 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
Usetype="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
timefor 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
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
border | border | Border radius of the toast component | "none" | "xs2" | "xs" | "s" | "m" | "l" | "full" | "s" |
hideIcon | hide-icon | If true, the semantic icon is hidden | boolean | false |
open | open | If true, the toast is visible | boolean | undefined |
placement | placement | Placement used by the fixed-position toast portal | "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | "bottom-center" |
time | time | Duration in milliseconds before the toast closes itself | number | 3000 |
type | type | Semantic type of the toast | "info" | "success" | "alert" | "error" | "loading" | "custom" | "info" |
Events
| Event | Description | Type |
|---|---|---|
bqHide | Fired when the toast is about to hide | CustomEvent<HTMLBqToastElement> |
bqShow | Fired when the toast is about to show | CustomEvent<HTMLBqToastElement> |
- 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
| Method | Description | Signature |
|---|---|---|
show() | Shows the toast programmatically | show() => Promise<void> |
hide() | Hides the toast programmatically | hide() => Promise<void> |
toast() | Renders the toast in the fixed-position stacking portal | toast() => Promise<void> |
Slots
| Slot | Description |
|---|---|
| (default) | The toast message content |
icon | Replaces the default icon with a custom bq-icon |
Shadow parts
| Part | Description |
|---|---|
wrapper | The internal wrapper that contains the icon and message |
icon-info | The <div> container that holds the icon component |
base | The root element of the internal default bq-icon |
svg | The <svg> element of the internal default bq-icon |
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.