ion-toast
A Toast is a subtle notification commonly used in modern applications. It can be used to provide feedback about an operation or to display a system message. The toast appears on top of the app's content, and can be dismissed by the app to resume user interaction with the app.
Inline Toasts (Recommended)
ion-toast
can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the toast.
Using isOpen
The isOpen
property on ion-toast
allows developers to control the presentation state of the toast from their application state. This means when isOpen
is set to true
the toast will be presented and when isOpen
is set to false
the toast will be dismissed.
isOpen
uses a one-way data binding, meaning it will not automatically be set to false
when the toast is dismissed. Developers should listen for the ionToastDidDismiss
or didDismiss
event and set isOpen
to false
. The reason for this is it prevents the internals of ion-toast
from being tightly coupled with the state of the application. With a one way data binding, the toast only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the toast needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug.
Controller Toasts
Dismissing
Toasts are intended to be subtle notifications and should not interrupt the user. As a result, user interaction should not be required to dismiss the toast.
The toast can be dismissed automatically after a specific amount of time by passing the number of milliseconds to display it in the duration
of the toast options. If a button with a role of "cancel"
is added, then that button will dismiss the toast. To dismiss the toast after creation, call the dismiss()
method on the instance.
Pressing the hardware back button does not dismiss toasts since they are not supposed to interrupt the user.
The following example demonstrates how to use the buttons
property to add a button that automatically dismisses the toast when clicked, as well as how to collect the role
of the dismiss event.
Console
Console messages will appear here when logged from the example above.
Positioning
Toasts can be positioned at the top, bottom or middle of the viewport. The position can be passed upon creation. The possible values are top
, bottom
and middle
. If the position is not specified, the toast will be displayed at the bottom of the viewport.
Relative Positioning
If a toast is presented alongside navigation elements such as a header, footer, or FAB, the toast may overlap these elements by default. This can be fixed using the positionAnchor
property, which takes either an element reference or an ID. The toast will be positioned relative to the chosen element, appearing below it when using position="top"
or above it when using position="bottom"
. When using position="middle"
, the positionAnchor
property is ignored.
Layout
Button containers within the toast can be displayed either on the same line as the message or stacked on separate lines using the layout
property. The stacked layout should be used with buttons that have long text values. Additionally, buttons in a stacked toast layout can use a side
value of either start
or end
, but not both.
Icons
An icon can be added next to the content inside of the toast. In general, icons in toasts should be used to add additional style or context, not to grab the user's attention or elevate the priority of the toast. If you wish to convey a higher priority message to the user or guarantee a response, we recommend using an Alert instead.
Theming
Accessibility
Focus Management
Toasts are intended to be subtle notifications and are not intended to interrupt the user. User interaction should not be required to dismiss the toast. As a result, focus is not automatically moved to a toast when one is presented.
Screen Readers
Toasts set aria properties in order to be accessible to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the toast is being used in an app.
Role
ion-toast
has role="status"
and aria-live="polite"
set on the inner .toast-content
element. This causes screen readers to only announce the toast message and header. Buttons and icons will not be announced when the toast is presented.
aria-live
causes screen readers to announce the content of the toast when it is updated. However, since the attribute is set to 'polite'
, screen readers should not interrupt the current task.
Since toasts are intended to be subtle notification, aria-live
should never be set to "assertive"
. If developers need to interrupt the user with an important message, we recommend using an alert.
Toast Buttons Description
Buttons containing text will be read by a screen reader when they are interacted with. If a button contains only an icon, or a description other than the existing text is desired, a label should be assigned to the button by passing aria-label
to the htmlAttributes
property on the button.
- Angular
- Javascript
- React
- Vue
const toast = await this.toastController.create({
header: 'Header',
buttons: [
{
icon: 'close',
htmlAttributes: {
'aria-label': 'close',
},
},
],
});
const toast = await this.toastController.create({
header: 'Header',
buttons: [
{
icon: 'close',
htmlAttributes: {
'aria-label': 'close',
},
},
],
});
useIonToast({
header: 'Header',
buttons: [
{
icon: 'close',
htmlAttributes: {
'aria-label': 'close',
},
},
],
});
const toast = await toastController.create({
header: 'Header',
buttons: [
{
icon: 'close',
htmlAttributes: {
'aria-label': 'close',
},
},
],
});