Snackbar Specification

Revision history

Version	User	Date	Notes
0.1	Zdravko Kolev	June 24, 2020	Update spec based on new `show` message parameter

Overview

igx-snackbar is a native Angular component part of the JS Blocks family. It provides feedback about an operation by showing brief message at the bottom of the screen on mobile and lower left on larger devices. igx-Snackbar will appear above all other elements on screen and only one can be displayed at a time.

igx-snackbar contains a single line of text directly related to the operation performed. It may contain a text action, but no icons.

Only one snackbar may be displayed at a time. Each snackbar may contain a single action, neither of which may be “Dismiss” or “Cancel”.

Objectives

Provide means for the citizen developers to implement a simple common case snackbar, yet customizable list item with minimal efforts.

User Stories

Developer

As a citizen developer, I want to be able to implement a material-styled toast component to notify users about occurred action and get input from them.

End user

As an end user, I want to have a toast pop-up whenever I performed an action that is important or could be ‘undone’.

Acceptance criteria

Single line
May contain text action
Icons
Be swiped off or automatically disappear
On top of screen stack
One snack bar could be present at a single time
The material design guidelines

Functionality

Snackbars automatically time out from the screen. For usability reasons, snackbars should not contain the only way to access a core use case. They should not be persistent or be stacked, as they are above other elements on screen.

There is only ever one snackbar displayed. When a second snackbar is triggered while the first is displayed, the first should start the contraction motion downwards before the second one animates upwards.

End User Experience

The igx-snackbar is a material styled component

Mark as read snackbar

Connection timmed out snackbar

Snackbar material layout guidelines

Developer Experience

Simple Snackbar

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

<igx-snackbar #snackbar
            message="This is a simple snackbar!">
</igx-snackbar>

You can be more descriptive and set message message="This is a simple snackbar!".

You can show the snackbar by using snackbar.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. You can place your message or any HTML element in the toast content which gives you a more powerful and diverse way of toast content handling.

Snackbar with button and action

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

<igx-snackbar #snackbar
             message="This is a snackbar with a button and action!"
             actionName="Dismiss"
             (onAction)="snackbar.hide()">
</igx-snackbar>

You can set the title of the button by setting actionName="Dismiss"; You can hide the Snackbar by using snackbar.hide() method.

The Snackbar will be automatically hidden after 4000 milliseconds, this can be controller by the displayTime attribute, the automatic hiding can be also controller by using the displayTime attribute.

Snackbar with custom content

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

<igx-snackbar #snackbar
             actionName="Dismiss"
             (onAction)="snackbar.hide()">
    <span>Custom content</span>
</igx-snackbar>

You can use content projection for displaying various content into the toast component. It also allows users to access toast styles through its host element.

User Interface

Placement

Snackbars appear above most elements on the screen, and they are equal in elevation to the floating action button. However, they are lower in elevation than dialogs, bottom sheets, and navigation drawers.

Behavior

Upon entrance, snackbars animate upwards from the bottom edge of the screen. When they appear, they do not block input. They exit by being swiped off-screen or automatically disappear after a timeout or user interaction elsewhere (such as summoning a new surface or activity).

Mobile Layout

Single-line snackbar height: 48dp
Multi-line snackbar height: 80dp
Text: Roboto Regular 14sp
Action button: Roboto Medium 14sp, all-caps text
Default background fill: #323232 100%

Desktop/tablet Layout

Single-line snackbar height: 48dp tall
Minimum width: 288dp
Maximum width: 568dp
2dp rounded corner
Text: Roboto Regular 14sp
Action button: Roboto Medium 14sp, all-caps text
Default background fill: #323232 100%
Alignment: Centered or left-aligned 24dp from the left and bottom edges of the screen

Navigation

The toast is a non-interactive component.

API

Properties
autoHide - Sets if the IgxToast component will be hidden after shown. The default value is true.
displayTime - The duration of time span in ms in which the IgxToast component will be visible after it is being shown. The default value is 4000.
isVisible - The IgxToast component visual state. The default value is false.
message - The message that will be shown message by the IgxToast component.
position - Specifies the position of the IgxToast component. Possible options are IgxToastPosition.Top, IgxToastPosition.Middle, IgxToastPosition.Bottom
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". Note: Content projection should take precedence over the message parameter;
hide() - Hides the IgxToast component.
Events
onShowing - Event is thrown prior toast is shown.
onShown - Event is shown when toast is shown.
onHiding - Event is thrown prior toast hidden.
onHidden - Event is thrown when toast hidden