Snackbar Specification

Revision history

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

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 snackbar component to notify users about occurred action and get input from them.

End user

As an end user, I want to have a snackbar 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

Note: Message input will be deprecated.

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, 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.

Snackbar 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-snackbar #toast>This is very important
</igx-snackbar>

..

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

Result: Another message This is very important

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!".

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>

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/gets if the snackbar will be automatically hidden after the displayTime is over.
displayTime - The duration of time span in ms in which the IgxSnackbar component will be visible after it is being shown. The default value is 4000.
isVisible - Represent the IgxSnackbar component visual state. The default value is false.
message - The message that will be shown message by the IgxSnackbar component.
actionText - Sets/gets the actionText attribute, which will be displayed in the action button.
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.
Events
onAction - An event that will be emitted when the action is executed. Provides reference to the IgxSnackbarComponent as an argument.
animationStarted - An event that will be emitted when the snackbar animation starts. Provides reference to the AnimationEvent interface as an argument.
animationDone - An event that will be emitted when the snackbar animation ends. Provides reference to the AnimationEvent interface as an argument.