Toast Specification

Revision history

Version	User	Date	Notes
0.1	Zdravko Kolev	June 24, 2020	Update spec based on new `show` message parameter
0.2	Desislava Dincheva	June 30, 2020	Update the API that toast provides

Overview

igx-toast is a circular-shaped component, usually used to indicate that there is an update on the status of the item related to (such as avatar, navigation menu, list item, or anywhere else in an app where some active indication is required).

<igx-toast message="Something happened">
</igx-toast>

Objectives

Equip citizen developers with a toast component that is primarily used for system messaging at the bottom of the screen. It will not contain actions and cannot be swiped off-screen.

User Stories

Developer

As a citizen developer, I want to be able to call a toast component programmatically so I can notify the application users with system critical messages that they could not swipe off the screen.

End-user

As an end user, I want to see a toast message on top of my application that gives me critical information that I must be aware of.

Acceptance criteria

Toast (system messaging):

Аppears at the bottom, middle or top of the screen
Contains text only (NO icons or buttons)
Мay NOT be swiped off - they disappear automatically

Functionality

End User Experience

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.

Toasts can be positioned at the top, bottom, or middle of the viewport and are dismissed automatically after a specific amount of time.

Developer Experience

<button (click)="toast.show()">Show toast</button>

<igx-toast #toast 
   message="This is very important!">
</igx-toast>

Note: Message input will be deprecated.

You can show the Toast by using toast.show() method, and change the message by passing a string value to the method e.g show("My custom message") or by using content projection, which gives you the capabilities to place your message or any HTML element in the toast content giving you a more powerful and diverse way of toast content handling.

Toast content and message precedence. If all of the below is set simultaneously:

Content projection will be shown along with show("custom message")/input message property if there is the following configuration:

<igx-toast #toast>This is very important
</igx-toast>

..

this.toast.show("Another message");

Result: Another message This is very important

User Interface

A toast provides simple feedback about an operation in a small popup. It only fills the amount of space required for the message and the current activity remains visible and interactive.

The end-user interface consists only of a text message.

Toast

Navigation

The toast is a non-interactive component.

API

Properties
autoHide - Sets if the IgxToast component will be hidden after shown. Default value is true.
displayTime - The duration of time span in ms which the IgxToast component will be visible after it is being shown. Default value is 4000.
isVisible - The IgxToast component visual state state. Default value is false.
message - The message that will be shown message by the IgxToast component.
position - sets/gets the position of the toast. If not set, the position attribute will have value IgxToastPosition.Bottom.
role - Sets/gets the role attribute. Default value is "alert".
Methods
show() - Shows the IgxToast component and hides it after some time span if autoHide is enabled.
show("My custom message") - Shows the IgxToast component with the passed message parameter - "My custom message".
hide() - Hides the IgxToast component.
toggle() - Toggles the visible state of the toast.
Events
onShowing- Emits an event prior the toast is shown. Provides reference to the IgxToastComponent as event argument.
onShown- Emits an event when the toast is already visible. Provides reference to the IgxToastComponent as event argument.
onHiding- Emits an event prior the toast is hidden. Provides reference to the IgxToastComponent as event argument.
onHidden- Emits an event when the toast is already not visible. Provides reference to the IgxToastComponent as event argument.