Switch branches/tags
chore/all/remove-event-handlers-from-adapters chore/button/alternates chore/checkbox/no-more-importants chore/image-list-screenshot chore/infra/high-contrast-rtl-screenshots chore/infra/not-old-ios chore/infrastructure/remove-normalize-css chore/license chore/list/list-item chore/package/update-sass-variables-to-default chore/select/update-adapter-value-methods chore/webpack/building-demos debugging-dumb-ios-tests docs/deploy-site docs/icon-button-meta-36 docs/survey-link-readmes-style docs/40 docs/41 drcampbell-fix/select-height experiment/drawer experimental/advorak/karma-cbt-runner experimental/browser-compat experimental/button-no-line-height experimental/card/ripple-surface experimental/drawer/ios-animation experimental/fab-mixins-kgf experimental_feat_extendedfab_issue2043 experimental_feat_extendedfab_transform experimental_feat_switch_colorscheme experimental/feature-targeting experimental/handlebars experimental/ie10-compat experimental/infra/button-flakiness experimental/lynnjepsen/screenshot-test experimental/m2-card-prototype experimental/menues1 experimental/outline-text-field experimental/ripple-cleanup-kgf experimental/ripple-ie-js-focus experimental/ripple-unbounded experimental/sassdoc experimental/screenshot-testing/cbt experimental/shape-ripple-ms experimental_shapes_system_mvp_single_radius experimental_shapes_system_mvp experimental/sliders/arrow-motions experimental/sliders/continuous experimental/sliders/discrete experimental/sliders/eventhandlers experimental/sliders/mixins experimental/sliders/ripple-states experimental/states-kgf experimental/states-nofocusripple-kgf experimental/states/selected experimental/text-field-outlined-flex experimental/textfield-improvements-prototype experimental_textfield_error_state_proposed experimental/theme/demo experimental/theme/disabled experimental/typescript-definitions feat/card/states-ripple-surface feat/chips/elevation-mixin feat/dialog feat_extendedfab_issue2043_roboto_font feat/invalid-input-label feat/list_toggle_tabindex feat/navigation-drawer-dismissible-foundation-update feat/navigation-drawer-modal feat/navigation-drawer-new feat/navigation-drawer-sass-improve feat/navigation-drawer-water feat/navigation-drawer feat/new-switch feat/rail-drawer feat/side-sheet-scss-cleanup feat/side-sheet feat/slider feat/sliders/arrow-motion feat/sliders/disabled feat/sliders/discrete feat/sliders/tick-mark-coloring feat/snackbar--prototype feat/tabs/tab-bar feat/tabs/tab-compute-dimensions feat/tabs/tab-handlers feat/tabs/tab-indicator-content feat/tabs/tab-indicator-in-tab feat/tabs/tab-scroller feat/tabs/tab feat/tabs/tabs-params-matching feat/test/button-assets-2-gcs feat/theme-emphasis fix/button/stroke-lineheight fix/checkbox/css-background-fade fix/chips/select fix/dialog-spec fix/drawer/fixture-js fix/drawer/page-scroll-issue fix/infrastructure/closure-module-declarations fix/list_checkbox_selectedindex fix/menu-surface-z-index fix/menu-surface/move-event-registration fix/menu/selection-group-styles fix/node-version-travisci fix/notched-outline/fix-overflow fix/outlined-shape-radius fix/slider/center fix/text-field/outline-color fix/textarea-center greenkeeper/autoprefixer-9.2.0 greenkeeper/autoprefixer-9.2.1 greenkeeper/autoprefixer-9.3.0 greenkeeper/autoprefixer-9.3.1 greenkeeper/autoprefixer-9.4.0 greenkeeper/autoprefixer-9.4.1 greenkeeper/autoprefixer-9.4.2 greenkeeper/babel-loader-8.0.0 greenkeeper/babel-loader-8.0.1 greenkeeper/babel-loader-8.0.2 greenkeeper/babel-loader-8.0.3 greenkeeper/babel-loader-8.0.4 greenkeeper/colors-1.3.3 greenkeeper/conventional-commits-parser-3.0.1 greenkeeper/css-loader-2.0.1 greenkeeper/dart-sass-1.15.0 greenkeeper/dart-sass-1.15.1 greenkeeper/dart-sass-1.15.2 greenkeeper/detect-port-1.3.0 greenkeeper/fibers-3.1.0 greenkeeper/fibers-3.1.1 greenkeeper/fs-extra-7.0.1 greenkeeper/google-closure-compiler-20181028.0.0 greenkeeper/google-closure-compiler-20181028.0.1 greenkeeper/google-closure-compiler-20181125.0.1 greenkeeper/google-closure-compiler-20181125.1.0 greenkeeper/google-closure-compiler-20181210.0.0 greenkeeper/husky-1.1.2 greenkeeper/husky-1.1.3 greenkeeper/husky-1.1.4 greenkeeper/husky-1.2.0 greenkeeper/husky-1.2.1 greenkeeper/karma-3.1.0 greenkeeper/karma-3.1.1 greenkeeper/karma-3.1.2 greenkeeper/karma-3.1.3 greenkeeper/karma-sauce-launcher-2.0.0 greenkeeper/karma-sauce-launcher-2.0.1 greenkeeper/karma-sauce-launcher-2.0.2 greenkeeper/karma-webpack-3.0.5 greenkeeper/lerna-2.10.1 greenkeeper/lerna-3.0.0 greenkeeper/lerna-3.0.1 greenkeeper/lerna-3.0.2 greenkeeper/lerna-3.0.3 greenkeeper/lerna-3.0.4 greenkeeper/lerna-3.0.5 greenkeeper/lerna-3.0.6 greenkeeper/lerna-3.1.0 greenkeeper/lerna-3.1.1 greenkeeper/lerna-3.1.2 greenkeeper/lerna-3.2.0 greenkeeper/lerna-3.2.1 greenkeeper/lerna-3.3.0 greenkeeper/lerna-3.3.1 greenkeeper/lerna-3.3.2 greenkeeper/lerna-3.4.0 greenkeeper/lerna-3.4.1 greenkeeper/lerna-3.4.2 greenkeeper/lerna-3.4.3 greenkeeper/lerna-3.5.0 greenkeeper/lerna-3.5.1 greenkeeper/lerna-3.6.0 greenkeeper/npm-run-all-4.1.4 greenkeeper/npm-run-all-4.1.5 greenkeeper/@octokit/rest-16.2.0 greenkeeper/recast-0.16.1 greenkeeper/semver-5.6.0 greenkeeper/simple-git-1.98.0 greenkeeper/simple-git-1.99.0 greenkeeper/simple-git-1.100.0 greenkeeper/simple-git-1.101.0 greenkeeper/simple-git-1.102.0 greenkeeper/simple-git-1.103.0 greenkeeper/simple-git-1.104.0 greenkeeper/simple-git-1.105.0 greenkeeper/simple-git-1.106.0 greenkeeper/simple-git-1.107.0 greenkeeper/standard-changelog-2.0.3 greenkeeper/standard-changelog-2.0.4 greenkeeper/standard-changelog-2.0.5 greenkeeper/standard-changelog-2.0.6 greenkeeper/stylelint-9.6.0 greenkeeper/stylelint-9.7.0 greenkeeper/stylelint-9.7.1 greenkeeper/stylelint-9.8.0 greenkeeper/stylelint-9.9.0 greenkeeper/stylelint-scss-3.3.1 greenkeeper/stylelint-scss-3.3.2 greenkeeper/stylelint-scss-3.4.0 greenkeeper/stylelint-scss-3.4.1 greenkeeper/stylelint-selector-bem-pattern-2.0.0 greenkeeper/testdouble-3.8.2 greenkeeper/testdouble-3.9.0 greenkeeper/testdouble-3.9.1 greenkeeper/webpack-4.0.0 greenkeeper/webpack-4.0.1 greenkeeper/webpack-4.1.0 greenkeeper/webpack-4.1.1 greenkeeper/webpack-4.2.0 greenkeeper/webpack-4.3.0 greenkeeper/webpack-4.4.0 greenkeeper/webpack-4.5.0 greenkeeper/webpack-4.6.0 greenkeeper/webpack-4.7.0 greenkeeper/webpack-4.8.2 greenkeeper/webpack-4.8.3 greenkeeper/webpack-4.9.0 greenkeeper/webpack-4.9.1 greenkeeper/webpack-4.9.2 greenkeeper/webpack-4.10.0 greenkeeper/webpack-4.10.1 greenkeeper/webpack-4.10.2 greenkeeper/webpack-4.11.0 greenkeeper/webpack-4.11.1 greenkeeper/webpack-4.12.0 greenkeeper/webpack-4.12.1 greenkeeper/webpack-4.12.2 greenkeeper/webpack-4.13.0 greenkeeper/webpack-4.14.0 greenkeeper/webpack-4.15.0 greenkeeper/webpack-4.15.1 greenkeeper/webpack-4.16.0 greenkeeper/webpack-4.16.1 greenkeeper/webpack-4.16.2 greenkeeper/webpack-4.16.3 greenkeeper/webpack-4.16.4 greenkeeper/webpack-4.16.5 greenkeeper/webpack-4.17.0 greenkeeper/webpack-4.17.1 greenkeeper/webpack-4.17.2 greenkeeper/webpack-4.17.3 greenkeeper/webpack-4.18.0 greenkeeper/webpack-4.18.1 greenkeeper/webpack-4.19.0 greenkeeper/webpack-4.19.1 greenkeeper/webpack-4.20.0 greenkeeper/webpack-4.20.1 greenkeeper/webpack-4.20.2 greenkeeper/webpack-4.21.0 greenkeeper/webpack-4.22.0 greenkeeper/webpack-4.23.0 greenkeeper/webpack-4.23.1 greenkeeper/webpack-4.24.0 greenkeeper/webpack-4.25.0 greenkeeper/webpack-4.25.1 greenkeeper/webpack-4.26.0 greenkeeper/webpack-4.26.1 greenkeeper/webpack-4.27.0 greenkeeper/webpack-4.27.1 greenkeeper/webpack-dev-server-3.0.0 greenkeeper/webpack-dev-server-3.1.0 greenkeeper/webpack-dev-server-3.1.1 greenkeeper/webpack-dev-server-3.1.2 greenkeeper/webpack-dev-server-3.1.3 greenkeeper/webpack-dev-server-3.1.4 greenkeeper/webpack-dev-server-3.1.5 greenkeeper/webpack-dev-server-3.1.6 greenkeeper/webpack-dev-server-3.1.7 greenkeeper/webpack-dev-server-3.1.8 greenkeeper/webpack-dev-server-3.1.9 greenkeeper/webpack-dev-server-3.1.10 latest-release list_custom_event_issue3481 list_custom_event_menu_update_issue3481 list_twolines_baseline_issue3038 maintenance/text-field master mock/crane origin/experimental/sliders patrickrodee-patch-1 patrickrodee-patch-2 refactor/text-field/opacity refactor/theme/color ripple/events ripple/prototype slider/mixins tabzzzzzzzzz test/switch-update textfields/verticalAlignment theme_alpha_variables_issue3066 typography_text_baseline
Nothing to show
Find file History
acdvorak feat(snackbar): Update to match latest design guidelines (#4166)
### Issues fixed

* Fixes #4005 (via new `mdc-snackbar-viewport-margin()` mixin)
* Fixes #3981
* Fixes #2916 (via new `MDCSnackbar:closing` and `MDCSnackbar:closed` events)
* Fixes #2628
* Fixes #1466 (via new `close()` method)
* Fixes #1398
* Fixes #1258
* Fixes #11 (the label now expands indefinitely to fit the text)
* Refs #2813

### Screenshots

![Baseline without action button](https://user-images.githubusercontent.com/409245/49956261-a080ca80-feb9-11e8-8287-b7e805344115.png)

![Baseline with action button](https://user-images.githubusercontent.com/409245/49956109-4a138c00-feb9-11e8-9213-3241fa86a1b8.png)

![Stacked layout](https://user-images.githubusercontent.com/409245/49956173-6a434b00-feb9-11e8-8a03-2e58ccc8f763.png)

BREAKING CHANGE: Snackbar's DOM and APIs have changed to match the latest design guidelines. See the Snackbar documentation for more information.
Latest commit 33d30e6 Dec 13, 2018

README.md

Snackbars

Snackbars provide brief messages about app processes at the bottom of the screen.

Design & API Documentation

Installation

npm install @material/snackbar

Basic Usage

HTML Structure

<div class="mdc-snackbar">
  <div class="mdc-snackbar__surface">
    <div class="mdc-snackbar__label"
         role="status"
         aria-live="polite">
      Can't send photo. Retry in 5 seconds.
    </div>
    <div class="mdc-snackbar__actions">
      <button type="button" class="mdc-button mdc-snackbar__action-button">Retry</button>
      <button class="mdc-icon-button mdc-snackbar__action-icon material-icons" title="Dismiss">close</button>
    </div>
  </div>
</div>

Styles

@import "@material/snackbar/mdc-snackbar";

JavaScript Instantiation

import {MDCSnackbar} from '@material/snackbar';
const snackbar = new MDCSnackbar(document.querySelector('.mdc-snackbar'));

See Importing the JS component for more information on how to import JavaScript.

Variants

Stacked

Action buttons with long text should be positioned below the label instead of alongside it. This can be accomplished by adding the mdc-snackbar--stacked modifier class to the root element:

<div class="mdc-snackbar mdc-snackbar--stacked">
  ...
</div>

Alternatively, you can call the mdc-snackbar-layout-stacked mixin from Sass:

@media (max-width: $mdc-snackbar-mobile-breakpoint) {
  .my-snackbar {
    @include mdc-snackbar-layout-stacked;
  }
}

Leading (tablet and desktop only)

By default, snackbars are centered horizontally within the viewport.

On larger screens, they can optionally be displayed on the leading edge of the screen (the left side in LTR, or the right side in RTL) by adding the mdc-snackbar--leading modifier class to the root element:

<div class="mdc-snackbar mdc-snackbar--leading">
  ...
</div>

Alternatively, you can call the mdc-snackbar-position-leading mixin from Sass:

@media (min-width: $mdc-snackbar-mobile-breakpoint) {
  .my-snackbar {
    @include mdc-snackbar-position-leading;
  }
}

Wide (tablet and desktop only)

To increase the margins between the snackbar and the viewport on larger screens, call the mdc-snackbar-viewport-margin mixin inside a media query:

@media (min-width: $mdc-snackbar-mobile-breakpoint) {
  .my-snackbar {
    @include mdc-snackbar-viewport-margin($mdc-snackbar-viewport-margin-wide);
  }
}

Style Customization

CSS Classes

CSS Class Description
mdc-snackbar Mandatory. Container for the snackbar elements.
mdc-snackbar__label Mandatory. Message text.
mdc-snackbar__actions Optional. Wraps the action button/icon elements, if present.
mdc-snackbar__action-button Optional. The action button.
mdc-snackbar__action-icon Optional. The dismiss ("X") icon.
mdc-snackbar--opening Optional. Applied automatically when the snackbar is in the process of animating open.
mdc-snackbar--open Optional. Indicates that the snackbar is open and visible.
mdc-snackbar--closing Optional. Applied automatically when the snackbar is in the process of animating closed.
mdc-snackbar--leading Optional. Positions the snackbar on the leading edge of the screen (left in LTR, right in RTL) instead of centered.
mdc-snackbar--stacked Optional. Positions the action button/icon below the label instead of alongside it.

Sass Mixins

Mixin Description
mdc-snackbar-fill-color($color) Sets the fill color of the snackbar.
mdc-snackbar-label-ink-color($color) Sets the color of the snackbar's label text.
mdc-snackbar-shape-radius($radius, $rtl-reflexive) Sets the rounded shape to snackbar surface with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
mdc-snackbar-min-width($min-width, $mobile-breakpoint) Sets the min-width of the surface on tablet/desktop devices. On mobile, the width is automatically set to 100%.
mdc-snackbar-max-width($max-width) Sets the max-width of the snackbar.
mdc-snackbar-elevation($z-index) Sets the elevation of the snackbar.
mdc-snackbar-viewport-margin($margin) Sets the distance between the snackbar and the viewport.
mdc-snackbar-z-index($z-index) Sets the z-index of the snackbar.
mdc-snackbar-position-leading() Positions the snackbar on the leading edge of the screen (left in LTR, right in RTL) instead of centered.
mdc-snackbar-layout-stacked() Positions the action button/icon below the label instead of alongside it.

NOTE: The mdc-snackbar__action-button and mdc-snackbar__action-icon elements can be customized with mdc-button and mdc-icon-button mixins.

JavaScript API

MDCSnackbar Properties

Property Value Type Description
isOpen boolean (read-only) Gets whether the snackbar is currently open.
timeoutMs number Gets/sets the automatic dismiss timeout in milliseconds. Value must be between 4000 and 10000 or an error will be thrown. Defaults to 5000 (5 seconds).
closeOnEscape boolean Gets/sets whether the snackbar closes when it is focused and the user presses the ESC key. Defaults to true.
labelText string Gets/sets the textContent of the label element.
actionButtonText string Gets/sets the textContent of the action button element.

NOTE: Setting labelText while the snackbar is open will cause screen readers to announce the new label. See Screen Readers below for more information.

MDCSnackbar Methods

Method Signature Description
open() => void Opens the snackbar.
close(reason: string=) => void Closes the snackbar, optionally with the specified reason indicating why it was closed.

Events

Event Name event.detail Description
MDCSnackbar:opening {} Indicates when the snackbar begins its opening animation.
MDCSnackbar:opened {} Indicates when the snackbar finishes its opening animation.
MDCSnackbar:closing {reason: ?string} Indicates when the snackbar begins its closing animation. reason contains the reason why the snackbar closed (dismiss or action).
MDCSnackbar:closed {reason: ?string} Indicates when the snackbar finishes its closing animation. reason contains the reason why the snackbar closed (dismiss or action).

Usage Within Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Snackbar for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCSnackbarAdapter Methods

Method Signature Description
addClass(className: string) => void Adds a class to the root element.
removeClass(className: string) => void Removes a class from the root element.
announce() => void Announces the snackbar's label text to screen reader users.
notifyOpening() => void Broadcasts an event denoting that the snackbar has just started opening.
notifyOpened() => void Broadcasts an event denoting that the snackbar has finished opening.
notifyClosing(reason: string) {} Broadcasts an event denoting that the snackbar has just started closing. If a non-empty reason is passed, the event's detail object should include its value in the reason property.
notifyClosed(reason: string) {} Broadcasts an event denoting that the snackbar has finished closing. If a non-empty reason is passed, the event's detail object should include its value in the reason property.

MDCSnackbarFoundation Methods

Method Signature Description
open() Opens the snackbar.
close(action: string) Closes the snackbar, optionally with the specified action indicating why it was closed.
isOpen() => boolean Returns whether the snackbar is open.
getTimeoutMs() => number Returns the automatic dismiss timeout in milliseconds.
setTimeoutMs(timeoutMs: number) Sets the automatic dismiss timeout in milliseconds. Value must be between 4000 and 10000 or an error will be thrown.
getCloseOnEscape() => boolean Returns whether the snackbar closes when it is focused and the user presses the ESC key.
setCloseOnEscape(closeOnEscape: boolean) => void Sets whether the snackbar closes when it is focused and the user presses the ESC key.
handleKeyDown(event: !KeyEvent) Handles keydown events on or within the snackbar's root element.
handleActionButtonClick(event: !MouseEvent) Handles click events on or within the action button.
handleActionIconClick(event: !MouseEvent) Handles click events on or within the dismiss icon.

Event Handlers

When wrapping the Snackbar foundation, the following events must be bound to the indicated foundation methods:

Event Target Foundation Handler Register Deregister
keydown .mdc-snackbar handleKeyDown During initialization During destruction
click .mdc-snackbar__action-button handleActionButtonClick During initialization During destruction
click .mdc-snackbar__action-icon handleActionIconClick During initialization During destruction

The Util API

External frameworks and libraries can use the following utility methods from the util module when implementing their own component.

Method Signature Description
announce(ariaEl: !HTMLElement, labelEl: !HTMLElement=) => void Announces the label text to screen reader users.

Alternatively, frameworks can use Closure Library's goog.a11y.aria.Announcer#say() method.

Accessibility

Screen Readers

Snackbars automatically announce their label text to screen reader users with a "polite" notification when open() is called.

However, screen readers only announce ARIA Live Regions when the element's textContent changes, so MDC Snackbar provides a util.announce() method to temporarily clear and then restore the label element's textContent.

NOTE: Setting labelText while the snackbar is open will cause screen readers to announce the new label.

util.announce() supports the latest versions of the following screen readers and browsers:

macOS VoiceOver is not supported at this time.

Dismiss Icon

A dedicated dismiss icon is optional, but strongly recommended. If the snackbar gets permanently "stuck" on the screen for any reason (e.g., #1398), the user needs to be able to manually dismiss it.

Dismiss Key

Pressing the ESC key while one of the snackbar's subelements has focus (e.g., the action button) will dismiss the snackbar.

To disable this behavior, set closeOnEscape to false.

No JS Ripples

The mdc-snackbar__action-button and mdc-snackbar__action-icon elements should not have JavaScript-enabled MDCRipple behavior.

When combined with the snackbar's exit animation, ripples cause too much motion, which can be distracting or disorienting for users.