@material/snackbar
Advanced tools
Changelog
14.0.0 (2022-04-27)
unset is unsupported in IE. (f460e23)validateTooltipWithCaretDistances method. (3e30054)theme-styles mixin... the value being retreived from the $theme map and css property name was swapped. The mixin would request font-size/font-weight/letter-spacing from the $theme map (which expects size/weight/tracking)... so these values would always be null. (32b3913)attachTo. (05db65e)showTimeout is not set (indicating that this tooltip is about to be re-shown). (6ca8b8f)minRange param to range sliders to request a minimum gap between the two thumbs. (8fffcb5)valueToAriaValueTextFn and valueToValueIndicatorTextFn functions are called for. (b6510c8)PiperOrigin-RevId: 444830518
PiperOrigin-RevId: 419837612
Readme
Snackbars provide brief messages about app processes at the bottom of the screen.
npm install @material/snackbar
<aside class="mdc-snackbar">
<div class="mdc-snackbar__surface" role="status" aria-relevant="additions">
<div class="mdc-snackbar__label" aria-atomic="false">
Can't send photo. Retry in 5 seconds.
</div>
<div class="mdc-snackbar__actions" aria-atomic="true">
<button type="button" class="mdc-button mdc-snackbar__action">
<div class="mdc-button__ripple"></div>
<span class="mdc-button__label">Retry</span>
</button>
</div>
</div>
</aside>
@use "@material/snackbar/mdc-snackbar";
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.
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:
<aside class="mdc-snackbar mdc-snackbar--stacked">
...
</aside>
Alternatively, you can call the layout-stacked mixin from Sass:
@use "@material/snackbar";
@media (max-width: snackbar.$mobile-breakpoint) {
.my-snackbar {
@include snackbar.layout-stacked;
}
}
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:
<aside class="mdc-snackbar mdc-snackbar--leading">
...
</aside>
Alternatively, you can call the position-leading mixin from Sass:
@media (min-width: snackbar.$mobile-breakpoint) {
.my-snackbar {
@include snackbar.position-leading;
}
}
To increase the margins between the snackbar and the viewport on larger screens, call the viewport-margin mixin inside a media query:
@media (min-width: snackbar.$mobile-breakpoint) {
.my-snackbar {
@include snackbar.viewport-margin(snackbar.$viewport-margin-wide);
}
}
| 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 | Optional. The action button. |
mdc-snackbar__dismiss | 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. |
| Mixin | Description |
|---|---|
fill-color($color) | Sets the fill color of the snackbar. |
label-ink-color($color) | Sets the color of the snackbar's label text. |
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. |
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%. |
max-width($max-width) | Sets the max-width of the snackbar. |
elevation($z-index) | Sets the elevation of the snackbar. |
viewport-margin($margin) | Sets the distance between the snackbar and the viewport. |
z-index($z-index) | Sets the z-index of the snackbar. |
position-leading() | Positions the snackbar on the leading edge of the screen (left in LTR, right in RTL) instead of centered. |
layout-stacked() | Positions the action button/icon below the label instead of alongside it. |
NOTE: The
mdc-snackbar__actionandmdc-snackbar__dismisselements can be further customized withmdc-buttonandmdc-icon-buttonmixins.
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 -1 to disable the timeout completely) 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
labelTextwhile 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. |
| 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', 'action', or undefined). |
MDCSnackbar:closed | {reason?: string} | Indicates when the snackbar finishes its closing animation. reason contains the reason why the snackbar closed ('dismiss', 'action', or undefined). |
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) => void | 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) => void | 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. |
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 | handleActionButtonClick | During initialization | During destruction |
click | .mdc-snackbar__dismiss | handleActionIconClick | During initialization | During destruction |
External frameworks and libraries can use the following utility methods from the util module when implementing their own component.
| Method Signature | Description |
|---|---|
announce(ariaEl: Element, labelEl?: Element) => void | Announces the label text to screen reader users. |
Alternatively, frameworks can use Closure Library's
goog.a11y.aria.Announcer#say()method.
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
labelTextwhile 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.
Snackbars are intended to dismiss on their own after a few seconds, but a dedicated dismiss icon may be optionally included as well for accessibility purposes.
Pressing the ESC key while one of the snackbar's child elements has focus (e.g., the action button) will dismiss the snackbar.
To disable this behavior, set closeOnEscape to false.
The mdc-snackbar__action and mdc-snackbar__dismiss 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.
FAQs
The Material Components for the web snackbar component
The npm package @material/snackbar receives a total of 901,657 weekly downloads. As such, @material/snackbar popularity was classified as popular.
We found that @material/snackbar demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 15 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.