StatusToast

Components/Feedback

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/statustoast

Overview

Copy

A status toast notifies users about a status change in an application.

Do

  • Use it to provide contextual feedback on the outcome of user action.
  • Use clear language and provide an actionable next step when applicable.
  • Provide one main action only (e.g., "Dismiss" or "Retry") to avoid complexity.
  • Use it to communicate status changes even when the user is inside a modal.

Don't

  • Don't add more than one action.
  • Don't use it for application-level messages. Use <SectionHelper/> instead.
  • Don't display identical toasts repeatedly. If an error persists, try a single persistent notification.
  • Don't use it as a navigation control between pages. Use <NavigationToast/> instead.

Feature examples

Status

Control the toast type with the status prop:

  • success is for a toast displayed after a successful action.
  • error is used for error messages and information about critical issues that prevent users from continuing.
  • warning is meant to draw the user's attention to unresolved issues that might affect the application but doesn't block the process.
  • info is for informational updates that aren't urgent.
Copy

Close button

Control whether the user can dismiss a status toast with thedismissible prop.

NOTE: If this is not enabled, error, warning and info toasts will remain visible on the screen until an action is taken or the issue is resolved.

Copy

Action

Add a button to a notification with the action prop. Offer one action only to avoid complexity.

Copy

Width

Component width is fixed to 600px. If the context exceeds the length, it will wrap to the next line.

Copy

Height

Minimum component height is 42px. The component height will grow together with the content. Height is not limited, so be cautious about using very long texts, as a long message will cover any content behind it.

Copy

Positioning

The position of a status toast is not customizable. <ToastContainer/> position is attached to the viewport with 26px gap from the bottom and not to the parent container or content within the page.

Copy

Timeout

Whether notification disappears automatically or not can be controlled with duration prop.

Recommended delay until toast disappears is at least 7 seconds.

When possible, it is recommended to make error toasts persistent, giving the user a chance to resolve the error or dismiss it at their own pace.

Copy

Stacking

By default, only one toast is visible at a time and the rest will be hidden under the first one.

However, you can control how many toast are visible at the same time. Up to thee toast can be visible at the same time. If more than given number is shown, they will be stacked with 6px gap between each other.

If three toasts are already visible, the newest one will be shown instead of the oldest one, until a slot is freed up by closing a toast, solving an issue, or it times out.

Copy

Common use case examples

In modals

Status toasts should be used inside of modals as well. Toasts in modals have the same logic as in pages. They appear at the same location, with an offset of 26px from the bottom of the page and have the same stacking behavior.

Copy

Code

Copy

Props

NameTypeDefaultDescription
actionReactNode—Action element to render.
childrenReactNode—Sets the message shown in the toast.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
dismissibleboolean—Whether the toast should render the dismiss button.
dismissLabelstring—Aria label for the dismiss button.
durationnull | number—Number in milliseconds to auto dismiss the toast. If the duration is set to 'null', toast won't be automatically dismissed.
idstring—Sets the id HTML attribute of the toast root element.
onDismiss(event?: MouseEvent<Element, MouseEvent> | undefined) => void—Callback function called whenever the user clicks the dismiss button.
status"error" | "warning" | "success" | "info"'info'Controls the icon, color and ARIA role of the toast. The 'error' and 'warning' statuses use the alert role, and the 'info' and 'success' statuses auto dismiss after 7000 milliseconds by default.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getStatus—
getContent—
getRole—
getAriaLive—
isVisible—
isDismissible—
getDismissButton—
dismissButton—
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — fix: the action stays visible on hover in Studio 2.0 (odeditor-dark). (#17542)
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.318.0 (2026-08-28) — maintenance release, no component-specific changes
  • 1.313.1 (2026-08-18) — fix: the action button text is now smaller in every theme. (#16792) — has visual changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.271.0 (2026-04-22) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.228.0 (2025-11-18) — maintenance release, no component-specific changes
  • 1.227.0 (2025-11-13) — feat: add mobile styles for StatusToast (#15491)
  • 1.216.0 (2025-09-01) — maintenance release, no component-specific changes
  • 1.207.0 (2025-07-24) — maintenance release, no component-specific changes
  • 1.204.1 (2025-07-09) — fix: improve StatusToast component layout and alignment (#15008)
  • 1.199.0 (2025-06-13) — maintenance release, no component-specific changes
  • 1.183.0 (2025-04-24) — maintenance release, no component-specific changes
  • 1.172.1 (2025-03-21) — maintenance release, no component-specific changes
  • 1.144.0 (2024-12-03) — breaking: reduced width (#14341)
  • 1.141.0 (2024-11-19) — feat: auto dismiss duration control & info status default duration (#14286)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.131.0 (2024-10-10) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?