blob: f5fdcb2926f6b2d5495a2044636d8b9093733a7e [file] [log] [blame]
Copybara botbe50d492023-11-30 00:16:42 +01001
2
3
4<h2 id="introduction">Introduction</h2>
5<p>The Material Design Lite (MDL) <strong>snackbar</strong> component is a container used to notify a user of an operation&#39;s status.
6It displays at the bottom of the screen.
7A snackbar may contain an action button to execute a command for the user.
8Actions should undo the committed action or retry it if it failed for example.
9Actions should not be to close the snackbar.
10By not providing an action, the snackbar becomes a <strong>toast</strong> component.</p>
11<h2 id="basic-usage-">Basic Usage:</h2>
12<p>Start a snackbar with a container div element.
13On that container define the <code>mdl-js-snackbar</code> and <code>mdl-snackbar</code> classes.
14It is also beneficial to add the aria live and atomic values to this container.</p>
15<p>Within the container create a container element for the message.
16This element should have the class <code>mdl-snackbar__text</code>.
17Leave this element empty!
18Text is added when the snackbar is called to be shown.</p>
19<p>Second in the container, add a button element.
20This element should have the class <code>mdl-snackbar__action</code>.
21It is recommended to set the type to button to make sure no forms get submitted by accident.
22Leave the text content empty here as well!
23Do not directly apply any event handlers.</p>
24<p>You now have complete markup for the snackbar to function.
25All that is left is within your JavaScript to call the <code>showSnackbar</code> method on the snackbar container.
26This takes a <a href="#data-object">plain object</a> to configure the snackbar content appropriately.
27You may call it multiple consecutive times and messages will stack.</p>
28<h2 id="examples">Examples</h2>
29<p>All snackbars should be shown through the same element.</p>
30<h4 id="markup-">Markup:</h4>
31<pre><code class="lang-html">&lt;div aria-live=&quot;assertive&quot; aria-atomic=&quot;true&quot; aria-relevant=&quot;text&quot; class=&quot;mdl-snackbar mdl-js-snackbar&quot;&gt;
32 &lt;div class=&quot;mdl-snackbar__text&quot;&gt;&lt;/div&gt;
33 &lt;button type=&quot;button&quot; class=&quot;mdl-snackbar__action&quot;&gt;&lt;/button&gt;
34&lt;/div&gt;
35</code></pre>
36<blockquote>
37<p>Note: In this example there are a few aria attributes for accessibility. Please modify these as-needed for your site.</p>
38</blockquote>
39<h3 id="snackbar">Snackbar</h3>
40<pre><code class="lang-javascript">var notification = document.querySelector(&#39;.mdl-js-snackbar&#39;);
41var data = {
42 message: &#39;Message Sent&#39;,
43 actionHandler: function(event) {},
44 actionText: &#39;Undo&#39;,
45 timeout: 10000
46};
47notification.MaterialSnackbar.showSnackbar(data);
48</code></pre>
49<h3 id="toast">Toast</h3>
50<pre><code class="lang-javascript">var notification = document.querySelector(&#39;.mdl-js-snackbar&#39;);
51notification.MaterialSnackbar.showSnackbar(
52 {
53 message: &#39;Image Uploaded&#39;
54 }
55);
56</code></pre>
57<h2 id="css-classes">CSS Classes</h2>
58<h3 id="blocks">Blocks</h3>
59<table>
60<thead>
61<tr>
62<th>MDL Class</th>
63<th>Effect</th>
64<th>Remarks</th>
65</tr>
66</thead>
67<tbody>
68<tr>
69<td><code>mdl-snackbar</code></td>
70<td>Defines the container of the snackbar component.</td>
71<td>Required on snackbar container</td>
72</tr>
73</tbody>
74</table>
75<h3 id="elements">Elements</h3>
76<table>
77<thead>
78<tr>
79<th>MDL Class</th>
80<th>Effect</th>
81<th>Remarks</th>
82</tr>
83</thead>
84<tbody>
85<tr>
86<td><code>mdl-snackbar__text</code></td>
87<td>Defines the element containing the text of the snackbar.</td>
88<td>Required</td>
89</tr>
90<tr>
91<td><code>mdl-snackbar__action</code></td>
92<td>Defines the element that triggers the action of a snackbar.</td>
93<td>Required</td>
94</tr>
95</tbody>
96</table>
97<h3 id="modifiers">Modifiers</h3>
98<table>
99<thead>
100<tr>
101<th>MDL Class</th>
102<th>Effect</th>
103<th>Remarks</th>
104</tr>
105</thead>
106<tbody>
107<tr>
108<td><code>mdl-snackbar--active</code></td>
109<td>Marks the snackbar as active which causes it to display.</td>
110<td>Required when active. Controlled in JavaScript</td>
111</tr>
112</tbody>
113</table>
114<h2 id="data-object">Data Object</h2>
115<p>The Snackbar components <code>showSnackbar</code> method takes an object for snackbar data.
116The table below shows the properties and their usage.</p>
117<table>
118<thead>
119<tr>
120<th>Property</th>
121<th>Effect</th>
122<th>Remarks</th>
123<th>Type</th>
124</tr>
125</thead>
126<tbody>
127<tr>
128<td>message</td>
129<td>The text message to display.</td>
130<td>Required</td>
131<td>String</td>
132</tr>
133<tr>
134<td>timeout</td>
135<td>The amount of time in milliseconds to show the snackbar.</td>
136<td>Optional (default 2750)</td>
137<td>Integer</td>
138</tr>
139<tr>
140<td>actionHandler</td>
141<td>The function to execute when the action is clicked.</td>
142<td>Optional</td>
143<td>Function</td>
144</tr>
145<tr>
146<td>actionText</td>
147<td>The text to display for the action button.</td>
148<td>Required if actionHandler is set</td>
149<td>String.</td>
150</tr>
151</tbody>
152</table>
153
154