Loading...
Skip to main content

Toasts

Push notifications to your visitors with a toast, a lightweight and easily customizable alert message.

Toasts are lightweight notifications designed to mimic the push notifications that have been popularized by mobile and desktop operating systems. They’re built with flexbox, so they’re easy to align and position.

Overview

Things to know when using the Toast model:

  • Toasts are opt-in: create a Toast model and mount its Component before calling open().
  • Toasts automatically hide after delay milliseconds; pass delay: 0 to keep one visible until it is dismissed.

The animation effect of this component is dependent on the prefers-reduced-motion media query.

Examples

Basic

To encourage extensible and predictable toasts, we recommend a header and body. Toast headers use display: flex, allowing easy alignment with margin and flexbox utilities passed through className.

Toasts are as flexible as you need and have very little required markup. At a minimum, we require a single element to contain your “toasted” content and strongly encourage a dismiss button.

<StaticToast body="Hello, world! This is a toast message." />

Live example

Click the button below to show a toast (positioned with our utilities in the lower right corner) that has been hidden by default.

Translucent

Toasts are slightly translucent to blend in with what’s below them.

<StaticToast body="Hello, world! This is a toast message." />

Pass translucent to ToastItem or Toast.open() to enhance the translucency with a backdrop blur and saturation filter.

<StaticToast
body="Hello, world! This is a toast message."
translucent
/>

Stacking

You can stack toasts by wrapping them in a toast container, which will vertically add some spacing.

<ToastContainer position="static">
<StaticToast body="Hello, world! This is a toast message." />
<StaticToast
body="Heads up, toasts will stack automatically"
time="2 seconds ago"
/>
</ToastContainer>

Dark toasts

Set a toast to dark mode by setting data-bs-theme="dark" on a parent element.

<StaticToast
body="Hello, world! This is a toast message."
dark
/>

Variants

Set the theme prop to apply a theme color to the toast. Use theme color utilities through className on individual elements.

<Stack gap={3}>
<StaticToast
body="Hello, world! This is a toast message."
noHeader
theme="primary"
/>
<StaticToast
body="Hello, world! This is a toast message."
noHeader
theme="accent"
/>
<StaticToast
body="Hello, world! This is a toast message."
noHeader
theme="secondary"
/>
<StaticToast
body="Hello, world! This is a toast message."
noHeader
theme="success"
/>
<StaticToast
body="Hello, world! This is a toast message."
noHeader
theme="danger"
/>
<StaticToast
body="Hello, world! This is a toast message."
noHeader
theme="warning"
/>
<StaticToast
body="Hello, world! This is a toast message."
noHeader
theme="info"
/>
<StaticToast
body="Hello, world! This is a toast message."
noHeader
theme="inverse"
/>
</Stack>

Custom content

Customize your toasts by removing sub-components, adding your own content, or passing utility class names through className. For example, render Icon for a hide control and use flexbox utilities to adjust the layout.

<StaticToast
body="Hello, world! This is a toast message."
noHeader
/>

Alternatively, you can also add additional controls and components to toasts.

<StaticToast
actions
body="Hello, world! This is a toast message."
/>

Instant

By default, toasts fade in and out. To disable the animation, pass instant to ToastItem or Toast.open(). The toast then appears without the CSS transition.

<StaticToast
body="Hello, world! This is a toast message."
instant
/>

Placement

Place toasts with custom CSS as you need them. The top right is often used for notifications, as is the top middle. Use the position prop on ToastContainer or toast.Component for a standard viewport position. If you’re only ever going to show one toast at a time, put the positioning styles right on ToastItem.

For systems that generate more notifications, consider using a wrapping element so they can easily stack.

<div
className="position-relative p-3"
style={{
minHeight: 180
}}
>
<ToastContainer
className="ms-auto"
position="static"
>
<StaticToast body="Hello, world! This is a toast message." />
</ToastContainer>
</div>

Use flexbox utilities through ToastContainer's className to align toasts horizontally or vertically.

<ToastContainer
className="mx-auto"
position="static"
>
<StaticToast body="Hello, world! This is a toast message." />
<StaticToast
body="Heads up, toasts will stack automatically"
time="2 seconds ago"
/>
</ToastContainer>

Accessibility

Toasts are intended to be small interruptions to your visitors or users, so to help those with screen readers and similar assistive technologies, you should wrap your toasts in an aria-live region. Changes to live regions (such as injecting/updating a toast component) are automatically announced by screen readers without needing to move the user’s focus or otherwise interrupt the user. Additionally, include aria-atomic="true" to ensure that the entire toast is always announced as a single (atomic) unit, rather than just announcing what was changed (which could lead to problems if you only update part of the toast’s content, or if displaying the same toast content at a later point in time). If the information needed is important for the process, e.g. for a list of errors in a form, then use the alert component instead of toast.

Note that the live region needs to be present in the markup before the toast is generated or updated. If you dynamically generate both at the same time and inject them into the page, they will generally not be announced by assistive technologies.

You also need to adapt the role and aria-live level depending on the content. If it’s an important message like an error, use role="alert" aria-live="assertive", otherwise use role="status" aria-live="polite" attributes.

BootstrapBootstrap11 mins ago
A polite status update with enough time to read.
<ToastContainer
aria-atomic="true"
aria-live="polite"
position="static"
>
<StaticToast
body="A polite status update with enough time to read."
live="polite"
/>
</ToastContainer>

As the content you’re displaying changes, be sure to update the delay timeout so that users have enough time to read the toast.

When using delay: 0, you must add a close button to allow users to dismiss the toast.

document/component/Document/ToastDemo.tsx
<ToastMessageDemo
body="This toast stays visible until you close it."
delay={0}
label="Show persistent toast"
/>

While technically it’s possible to add focusable/actionable controls (such as additional buttons or links) in your toast, you should avoid doing this for autohiding toasts. Even if you give the toast a long delay timeout, keyboard and assistive technology users may find it difficult to reach the toast in time to take action (since toasts don’t receive focus when they are displayed). If you absolutely must have further controls, we recommend using a toast with delay: 0.

CSS

Variables

Local CSS custom properties expose the component’s colors, spacing, borders, and transitions. Override them through style or a CSS module. The defaults below come from the Bootstrap stylesheet used by Idea React; see the upstream variable reference.

VariableDefault
--bs-toast-zindexvar(--bs-z-toast)
--bs-toast-padding-x1rem
--bs-toast-padding-y0.75rem
--bs-toast-spacing1.5rem
--bs-toast-max-width350px
--bs-toast-font-sizevar(--bs-font-size-sm)
--bs-toast-bgvar(--bs-bg-body)
--bs-toast-border-widthvar(--bs-border-width)
--bs-toast-border-colorvar(--bs-border-color-translucent)
--bs-toast-box-shadowvar(--bs-box-shadow)
--bs-toast-header-colorvar(--bs-fg-3)
--bs-toast-header-bgvar(--bs-bg-1)
--bs-toast-header-border-colorvar(--bs-border-color-translucent)
--bs-toast-transition-propertyopacity, display
--bs-toast-transition-duration0.15s
--bs-toast-transition-timinglinear

Usage

Create a Toast model and mount its Component to establish the live region before showing notifications. Call open({ title, body, delay }) to append a toast. The live example above demonstrates this React integration.

Options

Message optionDefaultDescription
bodyrequiredToast body as a React node.
title—Optional toast heading.
delay3000Milliseconds before hiding; 0 disables automatic dismissal.
idgeneratedSupply an ID to replace an existing notification or dismiss it later.
role"status"Use "alert" for urgent messages and an appropriate live-region priority.
theme—Contextual theme color.
translucentfalseBlur and saturate the background.
instantfalseSkip the CSS transition.

Methods

open(message) returns a promise that resolves when that notification closes. Call close(id) to dismiss an individual notification.

Documentation navigation
On this page
On this page