;
};
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](/components/notification) or [dialog](/components/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 toasts provide users with relevant information or guidance about a particular action or feature.
Error toasts inform the user about issues that occur during user interaction and provide guidance on how to resolve them.
Loading toasts indicate to users that a process is underway, such as data retrieval or content loading.
Success toasts confirm to users that an action has been completed successfully.
Warning toasts warn users about potential risks or issues that require attention.
Custom toasts are personalized messages tailored to specific user interactions or application contexts.
## 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.
| 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.
Keep the message short and direct. Limit the content to one or two brief sentences.
Include enough context for users to understand why the toast appeared and what happened.
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.
bq-toast[open] {
display: inline-block;
}
This is an informational message.Your profile was updated.Your session will expire soon.We couldn't complete the request.Uploading file...
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
This is an informational message.Your profile was updated.Your session will expire soon.We couldn't complete the request.Uploading file...
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqToast } from "@beeq/react";
<>
This is an informational message.Your profile was updated.Your session will expire soon.We couldn't complete the request.Uploading file...
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqToast } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqToast],
template: `
This is an informational message.Your profile was updated.Your session will expire soon.We couldn't complete the request.Uploading file...
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
This is an informational message.Your profile was updated.Your session will expire soon.We couldn't complete the request.Uploading file...
```
## Options
### Custom icon
Use `type="custom"` when you need a branded or domain-specific status cue. Replace the default icon through the `icon` slot.
bq-toast[open] {
display: inline-block;
}
New feature added to your workspace.
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
New feature added to your workspace.
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqToast } from "@beeq/react";
New feature added to your workspace.
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon, BqToast } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqIcon, BqToast],
template: `
New feature added to your workspace.
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
New feature added to your workspace.
```
### 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.
[data-toast-container] {
display: flex;
position: fixed;
z-index: 9999;
flex-direction: column;
gap: var(--bq-spacing-xs);
pointer-events: none;
inset-block-start: 10rem;
inset-inline-start: 50%;
transform: translateX(-50%);
align-items: center;
}
Toggle toast
`}
>
```js JavaScript icon="js" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
const TOAST_TYPE = ['info', 'success', 'alert', 'error', 'loading'];
const button = previewRoot.querySelector('bq-button');
const toastContainer = previewRoot.querySelector('[data-toast-container]');
const getRandomType = () => TOAST_TYPE[Math.floor(Math.random() * TOAST_TYPE.length)];
const createToast = (type, message) => {
const toast = document.createElement('bq-toast');
toast.setAttribute('type', type);
toast.setAttribute('time', '4000');
toast.textContent = message;
return toast;
};
button.addEventListener('bqClick', async () => {
await customElements.whenDefined('bq-toast');
const type = getRandomType();
const toast = createToast(type, 'This is a message');
toastContainer.appendChild(toast);
toast.open = true;
window.setTimeout(() => {
toast.open = false;
window.setTimeout(() => {
toast.remove();
}, 300);
}, 4000);
});
```
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Toggle toast
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { useEffect, useRef, useState } from "react";
import { createPortal } from "react-dom";
import { BqButton, BqToast } from "@beeq/react";
const TOAST_TYPES = ['info', 'success', 'alert', 'error', 'loading'];
export function ToastStackExample() {
const [toasts, setToasts] = useState([]);
const timerIds = useRef(new Set());
useEffect(() => () => timerIds.current.forEach(clearTimeout), []);
const handleClick = () => {
const id = Date.now();
const type = TOAST_TYPES[Math.floor(Math.random() * TOAST_TYPES.length)];
setToasts((prev) => [...prev, { id, type }]);
const timer = window.setTimeout(() => {
setToasts((prev) => prev.filter((t) => t.id !== id));
timerIds.current.delete(timer);
}, 4000);
timerIds.current.add(timer);
};
return (
<>
Toggle toast
{createPortal(
{toasts.map(({ id, type }) => (
This is a message
))}
```
## Best practices
Do
Keep toast copy short, direct, and written in sentence case.
Don't
Don't use a toast for long explanations, multi-step guidance, or anything users may need to revisit later.
Do
Use the correct semantic `type` so icon and color reinforce the meaning immediately.
Don't
Don't flood the interface with many simultaneous toasts. If several events occur, queue or stack them in a controlled order.
Do
Place viewport toasts where they do not cover bottom navigation, floating actions, or other critical controls.
Don't
Don't rely on a toast alone for critical errors or irreversible outcomes that require acknowledgment.
Do
Set a long enough `time` for users who may need more seconds to read the message, especially if it contains an error explanation.
Don't
Do 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
| 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` |
| `bqShow` | Fired when the toast is about to show | `CustomEvent` |
* 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` |
| `hide()` | Hides the toast programmatically | `hide() => Promise` |
| `toast()` | Renders the toast in the fixed-position stacking portal | `toast() => Promise` |
### 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 `
` container that holds the icon component |
| `base` | The root element of the internal default `bq-icon` |
| `svg` | The `
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.
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.
| 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 |