Skip to main content
Version: v8 (beta)

ion-toast

shadow

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.

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.

Swipe to Dismiss

Toasts can be swiped to dismiss by using the swipeGesture property. This feature is position-aware, meaning the direction that users need to swipe will change based on the value of the position property. Additionally, the distance users need to swipe may be impacted by the positionAnchor property.

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.

const toast = await this.toastController.create({
header: 'Header',
buttons: [
{
icon: 'close',
htmlAttributes: {
'aria-label': 'close',
},
},
],
});

Tips

While this is not a complete list, here are some guidelines to follow when using toasts.

  • Do not require user interaction to dismiss toasts. For example, having a "Dismiss" button in the toast is fine, but the toast should also automatically dismiss on its own after a timeout period. If you need user interaction for a notification, consider using an alert instead.

  • For toasts with long messages, consider adjusting the duration property to allow users enough time to read the content of the toast.

  • If adding buttons to a toast, always provide alternative ways of completing the actions associated with each button. This ensures that even if the toast dismisses before a user can read it, they can still complete the actions shown in the toast.

  • Avoid showing a toast with buttons from inside another overlay such as a modal. Modals and other overlays implement focus trapping that will prevent screen readers from moving focus to the toast to complete the actions. This may be confusing for users since the toast will still be announced by screen readers. This is true even if alternative ways of completing the actions associated with each button are implemented. Consider creating a live region within the focus-trapped modal instead of using a toast.

Interfaces

ToastButton

interface ToastButton {
text?: string;
icon?: string;
side?: 'start' | 'end';
role?: 'cancel' | string;
cssClass?: string | string[];
htmlAttributes?: { [key: string]: any };
handler?: () => boolean | void | Promise<boolean | void>;
}

ToastOptions

interface ToastOptions {
header?: string;
message?: string | IonicSafeString;
cssClass?: string | string[];
duration?: number;
buttons?: (ToastButton | string)[];
position?: 'top' | 'bottom' | 'middle';
translucent?: boolean;
animated?: boolean;
icon?: string;
htmlAttributes?: { [key: string]: any };

color?: Color;
mode?: Mode;
keyboardClose?: boolean;
id?: string;

enterAnimation?: AnimationBuilder;
leaveAnimation?: AnimationBuilder;
}

Properties

animated

DescriptionIf true, the toast will animate.
Attributeanimated
Typeboolean
Defaulttrue

buttons

DescriptionAn array of buttons for the toast.
Attributeundefined
Type(string | ToastButton)[] | undefined
Defaultundefined

color

DescriptionThe color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming.
Attributecolor
Type"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string | undefined
Defaultundefined

cssClass

DescriptionAdditional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces.
Attributecss-class
Typestring | string[] | undefined
Defaultundefined

duration

DescriptionHow many milliseconds to wait before hiding the toast. By default, it will show until dismiss() is called.
Attributeduration
Typenumber
Defaultconfig.getNumber('toastDuration', 0)

enterAnimation

DescriptionAnimation to use when the toast is presented.
Attributeundefined
Type((baseEl: any, opts?: any) => Animation) | undefined
Defaultundefined
DescriptionHeader to be shown in the toast.
Attributeheader
Typestring | undefined
Defaultundefined

htmlAttributes

DescriptionAdditional attributes to pass to the toast.
Attributeundefined
Typeundefined | { [key: string]: any; }
Defaultundefined

icon

DescriptionThe name of the icon to display, or the path to a valid SVG file. See ion-icon. https://ionic.io/ionicons
Attributeicon
Typestring | undefined
Defaultundefined

isOpen

DescriptionIf true, the toast will open. If false, the toast will close. Use this if you need finer grained control over presentation, otherwise just use the toastController or the trigger property. Note: isOpen will not automatically be set back to false when the toast dismisses. You will need to do that in your code.
Attributeis-open
Typeboolean
Defaultfalse

keyboardClose

DescriptionIf true, the keyboard will be automatically dismissed when the overlay is presented.
Attributekeyboard-close
Typeboolean
Defaultfalse

layout

DescriptionDefines how the message and buttons are laid out in the toast. 'baseline': The message and the buttons will appear on the same line. Message text may wrap within the message container. 'stacked': The buttons containers and message will stack on top of each other. Use this if you have long text in your buttons.
Attributelayout
Type"baseline" | "stacked"
Default'baseline'

leaveAnimation

DescriptionAnimation to use when the toast is dismissed.
Attributeundefined
Type((baseEl: any, opts?: any) => Animation) | undefined
Defaultundefined

message

DescriptionMessage to be shown in the toast. This property accepts custom HTML as a string. Content is parsed as plaintext by default. innerHTMLTemplatesEnabled must be set to true in the Ionic config before custom HTML can be used.
Attributemessage
TypeIonicSafeString | string | undefined
Defaultundefined

mode

DescriptionThe mode determines which platform styles to use.
Attributemode
Type"ios" | "md"
Defaultundefined

position

DescriptionThe starting position of the toast on the screen. Can be tweaked further using the positionAnchor property.
Attributeposition
Type"bottom" | "middle" | "top"
Default'bottom'

positionAnchor

DescriptionThe element to anchor the toast's position to. Can be set as a direct reference or the ID of the element. With position="bottom", the toast will sit above the chosen element. With position="top", the toast will sit below the chosen element. With position="middle", the value of positionAnchor is ignored.
Attributeposition-anchor
TypeHTMLElement | string | undefined
Defaultundefined

swipeGesture

DescriptionIf set to 'vertical', the Toast can be dismissed with a swipe gesture. The swipe direction is determined by the value of the position property: top: The Toast can be swiped up to dismiss. bottom: The Toast can be swiped down to dismiss. middle: The Toast can be swiped up or down to dismiss.
Attributeswipe-gesture
Type"vertical" | undefined
Defaultundefined

translucent

DescriptionIf true, the toast will be translucent. Only applies when the mode is "ios" and the device supports backdrop-filter.
Attributetranslucent
Typeboolean
Defaultfalse

trigger

DescriptionAn ID corresponding to the trigger element that causes the toast to open when clicked.
Attributetrigger
Typestring | undefined
Defaultundefined

Events

NameDescription
didDismissEmitted after the toast has dismissed. Shorthand for ionToastDidDismiss.
didPresentEmitted after the toast has presented. Shorthand for ionToastWillDismiss.
ionToastDidDismissEmitted after the toast has dismissed.
ionToastDidPresentEmitted after the toast has presented.
ionToastWillDismissEmitted before the toast has dismissed.
ionToastWillPresentEmitted before the toast has presented.
willDismissEmitted before the toast has dismissed. Shorthand for ionToastWillDismiss.
willPresentEmitted before the toast has presented. Shorthand for ionToastWillPresent.

Methods

dismiss

DescriptionDismiss the toast overlay after it has been presented.
Signaturedismiss(data?: any, role?: string) => Promise<boolean>

onDidDismiss

DescriptionReturns a promise that resolves when the toast did dismiss.
SignatureonDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

DescriptionReturns a promise that resolves when the toast will dismiss.
SignatureonWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present

DescriptionPresent the toast overlay after it has been created.
Signaturepresent() => Promise<void>

CSS Shadow Parts

NameDescription
buttonAny button element that is displayed inside of the toast.
button cancelAny button element with role "cancel" that is displayed inside of the toast.
containerThe element that wraps all child elements.
headerThe header text of the toast.
iconThe icon that appears next to the toast content.
messageThe body text of the toast.

CSS Custom Properties

NameDescription
--backgroundBackground of the toast
--border-colorBorder color of the toast
--border-radiusBorder radius of the toast
--border-styleBorder style of the toast
--border-widthBorder width of the toast
--box-shadowBox shadow of the toast
--button-colorColor of the button text
--colorColor of the toast text
--endPosition from the right if direction is left-to-right, and from the left if direction is right-to-left
--heightHeight of the toast
--max-heightMaximum height of the toast
--max-widthMaximum width of the toast
--min-heightMinimum height of the toast
--min-widthMinimum width of the toast
--startPosition from the left if direction is left-to-right, and from the right if direction is right-to-left
--white-spaceWhite space of the toast message
--widthWidth of the toast

Slots

No slots available for this component.