React documentation
Last modified:
BcToast
Toast is available as a React component with BcToast.
BcToast uses an instance of ToastStore to keep and manage messages.
BcToast follows a singleton pattern and you only need 1 instance of it in your application. All you need to do use the methods of the ToastStore.
BcToast Props
| Prop | Type | Required? | Default | Description |
|---|---|---|---|---|
timeout | number | optional | 6000 | The time before the toast is auto-dismissed. |
BcToast methods
The BcToast component also provides 4 methods:
- BcToast.message
- BcToast.error
- BcToast.success
- BcToast.warning
These methods are just wrappers around an instance of the ToastStore methods. Please see ToastStore section below.
BcToastMessage
BcToastMessage is the actual component which renders the BcPageAlert to display the message to the user.
As a developer, you will not have to interact with this component. The only way to interact with this component is via BcToast and the methods exposed on BcToast.
BcToastMessage Props
BcToastMessage props extends ToastMessage.
Additional Props
| Prop | Type | Required? | Default | Description |
|---|---|---|---|---|
timeout | boolean | optional | 6000 | Time in milliseconds before the toast is automatically dismissedauto-dismiss. |
ToastStore
The ToastStore is a state management class for toast messages and BcToast creates an instance of ToastStore to subscribe to events from that store.
ToastStore leverages React’s useExternalSyncStore API but also exposes getters and setters to interact with the private static field toastMessage.
ToastMessage signature
| Property | Type | Required? | Default | Description |
|---|---|---|---|---|
| autoDismiss | boolean | No | false | If you need a toast to dismiss automatically, then set autoDismiss to the message. autoDismiss is set at the message level so you can decide which message can be auto dismissed and which cannot. The autoDismiss counter will only start once the message is rendered to the user.When autoDismiss is on, interactivity props are spread on the toast such that hovering over the toast will prevent dismissal and moving off the toast will restart the dismissal countdown. |
| content | string | Yes | This is the SHORT message to display to the user There is a width limit on the ToastMessage component of 400px so if your message is longer than that width, the toast will get taller; and no there is no props to change that width. So try to keep your message short and sweet. | |
| type | "error" | "success" | "warning" | No | Update the color of the toast message. The toast message styling follows the BcPageAlert styling. Linking it to BcPageAlertVariant so we are aware of changes in BcPageAlert which might affect our toast. |
| Method | Params | Description |
|---|---|---|
| addMessage | ToastMessage | This method allows you to add a custom message to the store. |
| error | (message: string, autoDismiss: boolean ) => void | Display an error toast. autoDismiss is set to true by default. |
| success | (message: string, autoDismiss: boolean ) => void | Display a success toast. autoDismiss is set to true by default. |
| warning | (message: string, autoDismiss: boolean ) => void | Display a warning toast. autoDismiss is set to true by default. |
HTML
Last modified:
When creating Toasts, they should be an ARIA live region. Please read more about accessibility
To make sure the ARIA live region works properly, make sure only the content of the Toast is updated and not the whole Toast element.
Design
Last modified:
Toasts are styled as “floating” super-imposed Page alerts.
Toasts are positioned at the bottom of the screen to indicate their app or page-wide status.
Toasts are positioned with a z-index in the foreground layer. This ensures they display above the page but not above modals or modal overlays.
The ToastMessage component has a width of 25rem so if your message is longer than that width, the toast will get taller; and no there is no props to change that width. So try to keep your message short and sweet.
Accessibility
Last modified:
Toast notifications give users important alerts so making them accessible is important.
Toasts are ARIA live regions with minor differences in ARIA attributes, eg. error and success have a different role:
| Type | ARIA role | ‘Politeness’ |
|---|---|---|
| error | alert | assertive |
| success | status | polite |
| warning | alert | assertive |
| undefined | status | polite |
Finally give Toasts an aria-label to provide a summarizing title for the Toast’s content.
Rationale
Last modified:
We used the name ‘Toast’ because of the way updates ‘pop-up’ from the bottom of the screen.
Toasts are non-disruptive in nature and intended to provide an at-a-glance feedback of an action. This is the reason they appear at the bottom of the screen, because they are out of the way and temporary.
Typically toasts should be used for success/informational system messages rather than errors, this is because errors typically require a subsequent action that the user must perform to continue. So given the temporary and brief nature of toasts, it can be hard to understand what the user needs to do, therefore a page alert might be more suitable. (This one might be better elsewhere)
See also
Last modified: