Stripped personal data from development repository
view | history | commit | commitdiff
Samo Penic
2019-02-20 83c3f647c35477564b77cbc5b36d37d793d5442a
commit | author | age
83c3f6 1 ---
SP 2 layout: docs
3 title: Toasts
4 description: Push notifications to your visitors with a toast, a lightweight and easily customizable alert message.
5 group: components
6 toc: true
7 ---
8
9 Toasts are lightweight notifications designed to mimic the push notifications that have been popularized by mobile and desktop operating systems. They're built with flexbox, so they're easy to align and position.
10
11 ## Overview
12
13 Things to know when using the toast plugin:
14
15 - If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
16 - Toasts are opt-in for performance reasons, so **you must initialize them yourself**.
17 - Toasts will automatically hide if you do not specify `autohide: false`.
18
19 ## Examples
20
21 ### Basic
22
23 To encourage extensible and predictable toasts, we recommend a header and body. Toast headers use `display: flex`, allowing easy alignment of content thanks to our margin and flexbox utilities.
24
25 Toasts are as flexible as you need and have very little required markup. At a minimum, we require a single element to contain your "toasted" content and strongly encourage a dismiss button.
26
27 <div class="bg-light">
28 {% capture example %}
29 <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
30   <div class="toast-header">
31     {% include icons/placeholder.svg width="20" height="20" background="#007aff" class="rounded mr-2" text=" " title=" " %}
32     <strong class="mr-auto">Bootstrap</strong>
33     <small>11 mins ago</small>
34     <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
35       <span aria-hidden="true">&times;</span>
36     </button>
37   </div>
38   <div class="toast-body">
39     Hello, world! This is a toast message.
40   </div>
41 </div>
42 {% endcapture %}
43 {% include example.html content=example %}
44 </div>
45
46 ### Translucent
47
48 Toasts are slightly translucent, too, so they blend over whatever they might appear over. For browsers that support the `backdrop-filter` CSS property, we'll also attempt to blur the elements under a toast.
49
50 <div class="bg-dark">
51 {% capture example %}
52 <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
53   <div class="toast-header">
54     {% include icons/placeholder.svg width="20" height="20" background="#007aff" class="rounded mr-2" text=" " title=" " %}
55     <strong class="mr-auto">Bootstrap</strong>
56     <small class="text-muted">11 mins ago</small>
57     <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
58       <span aria-hidden="true">&times;</span>
59     </button>
60   </div>
61   <div class="toast-body">
62     Hello, world! This is a toast message.
63   </div>
64 </div>
65 {% endcapture %}
66 {% include example.html content=example %}
67 </div>
68
69 ### Stacking
70
71 When you have multiple toasts, we default to vertiaclly stacking them in a readable manner.
72
73 <div class="bg-light">
74 {% capture example %}
75 <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
76   <div class="toast-header">
77     {% include icons/placeholder.svg width="20" height="20" background="#007aff" class="rounded mr-2" text=" " title=" " %}
78     <strong class="mr-auto">Bootstrap</strong>
79     <small class="text-muted">just now</small>
80     <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
81       <span aria-hidden="true">&times;</span>
82     </button>
83   </div>
84   <div class="toast-body">
85     See? Just like this.
86   </div>
87 </div>
88
89 <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
90   <div class="toast-header">
91     {% include icons/placeholder.svg width="20" height="20" background="#007aff" class="rounded mr-2" text=" " title=" " %}
92     <strong class="mr-auto">Bootstrap</strong>
93     <small class="text-muted">2 seconds ago</small>
94     <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
95       <span aria-hidden="true">&times;</span>
96     </button>
97   </div>
98   <div class="toast-body">
99     Heads up, toasts will stack automatically
100   </div>
101 </div>
102 {% endcapture %}
103 {% include example.html content=example %}
104 </div>
105
106 ## Placement
107
108 Place toasts with custom CSS as you need them. The top right is often used for notifications, as is the top middle. If you're only ever going to show one toast at a time, put the positioning styles right on the `.toast`.
109
110 <div class="bg-dark">
111 {% capture example %}
112 <div aria-live="polite" aria-atomic="true" style="position: relative; min-height: 200px;">
113   <div class="toast" style="position: absolute; top: 0; right: 0;">
114     <div class="toast-header">
115       {% include icons/placeholder.svg width="20" height="20" background="#007aff" class="rounded mr-2" text=" " title=" " %}
116       <strong class="mr-auto">Bootstrap</strong>
117       <small>11 mins ago</small>
118       <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
119         <span aria-hidden="true">&times;</span>
120       </button>
121     </div>
122     <div class="toast-body">
123       Hello, world! This is a toast message.
124     </div>
125   </div>
126 </div>
127 {% endcapture %}
128 {% include example.html content=example %}
129 </div>
130
131 For systems that generate more notifications, consider using a wrapping element so they can easily stack.
132
133 <div class="bg-dark">
134 {% capture example %}
135 <div aria-live="polite" aria-atomic="true" style="position: relative; min-height: 200px;">
136   <!-- Position it -->
137   <div style="position: absolute; top: 0; right: 0;">
138
139     <!-- Then put toasts within -->
140     <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
141       <div class="toast-header">
142         {% include icons/placeholder.svg width="20" height="20" background="#007aff" class="rounded mr-2" text=" " title=" " %}
143         <strong class="mr-auto">Bootstrap</strong>
144         <small class="text-muted">just now</small>
145         <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
146           <span aria-hidden="true">&times;</span>
147         </button>
148       </div>
149       <div class="toast-body">
150         See? Just like this.
151       </div>
152     </div>
153
154     <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
155       <div class="toast-header">
156         {% include icons/placeholder.svg width="20" height="20" background="#007aff" class="rounded mr-2" text=" " title=" " %}
157         <strong class="mr-auto">Bootstrap</strong>
158         <small class="text-muted">2 seconds ago</small>
159         <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
160           <span aria-hidden="true">&times;</span>
161         </button>
162       </div>
163       <div class="toast-body">
164         Heads up, toasts will stack automatically
165       </div>
166     </div>
167   </div>
168 </div>
169 {% endcapture %}
170 {% include example.html content=example %}
171 </div>
172
173 You can also get fancy with flexbox utilities to align toasts horizontally and/or vertically.
174
175 <div class="bg-dark">
176 {% capture example html %}
177 <!-- Flexbox container for aligning the toasts -->
178 <div aria-live="polite" aria-atomic="true" class="d-flex justify-content-center align-items-center" style="min-height: 200px;">
179
180   <!-- Then put toasts within -->
181   <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
182     <div class="toast-header">
183       {% include icons/placeholder.svg width="20" height="20" background="#007aff" class="rounded mr-2" text=" " title=" " %}
184       <strong class="mr-auto">Bootstrap</strong>
185       <small>11 mins ago</small>
186       <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
187         <span aria-hidden="true">&times;</span>
188       </button>
189     </div>
190     <div class="toast-body">
191       Hello, world! This is a toast message.
192     </div>
193   </div>
194 </div>
195 {% endcapture %}
196 {% include example.html content=example %}
197 </div>
198
199 ## Accessibility
200
201 Toasts are intended to be small interruptions to your visitors or users, so to help those with screen readers and similar assistive technologies, you should wrap your toasts in an [`aria-live` region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions). Changes to live regions (such as injecting/updating a toast component) are automatically announced by screen readers without needing to move the user's focus or otherwise interrupt the user. Additionally, include `aria-atomic="true"` to ensure that the entire toast is always announced as a single (atomic) unit, rather than announcing what was changed (which could lead to problems if you only update part of the toast's content, or if displaying the same toast content at a later point in time). If the information needed is important for the process, e.g. for a list of errors in a form, then use the [alert component]({{ site.baseurl }}/docs/{{ site.docs_version }}/components/alerts/) instead of toast.
202
203 Note that the live region needs to be present in the markup *before* the toast is generated or updated. If you dynamically generate both at the same time and inject them into the page, they will generally not be announced by assistive technologies.
204
205 You also need to adapt the `role` and `aria-live` level depending on the content. If it's an important message like an error, use `role="alert" aria-live="assertive"`, otherwise use `role="status" aria-live="polite"` attributes.
206
207 As the content you're displaying changes, be sure to update the [`delay` timeout](#options) to ensure people have enough time to read the toast.
208
209 {% highlight html %}
210 <div class="toast" role="alert" aria-live="polite" aria-atomic="true" data-delay="10000">
211   <div role="alert" aria-live="assertive" aria-atomic="true">...</div>
212 </div>
213 {% endhighlight %}
214
215 When using `autohide: false`, you must add a close button to allow users to dismiss the toast.
216
217 <div class="bg-light">
218 {% capture example %}
219 <div role="alert" aria-live="assertive" aria-atomic="true" class="toast" data-autohide="false">
220   <div class="toast-header">
221     {% include icons/placeholder.svg width="20" height="20" background="#007aff" class="rounded mr-2" text=" " title=" " %}
222     <strong class="mr-auto">Bootstrap</strong>
223     <small>11 mins ago</small>
224     <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
225       <span aria-hidden="true">&times;</span>
226     </button>
227   </div>
228   <div class="toast-body">
229     Hello, world! This is a toast message.
230   </div>
231 </div>
232 {% endcapture %}
233 {% include example.html content=example %}
234 </div>
235
236 ## JavaScript behavior
237
238 ### Usage
239
240 Initialize toasts via JavaScript:
241
242 {% highlight js %}
243 $('.toast').toast(option)
244 {% endhighlight %}
245
246 ### Options
247
248 Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-animation=""`.
249
250 <table class="table table-bordered table-striped">
251   <thead>
252     <tr>
253       <th style="width: 100px;">Name</th>
254       <th style="width: 100px;">Type</th>
255       <th style="width: 50px;">Default</th>
256       <th>Description</th>
257     </tr>
258   </thead>
259   <tbody>
260     <tr>
261       <td>animation</td>
262       <td>boolean</td>
263       <td>true</td>
264       <td>Apply a CSS fade transition to the toast</td>
265     </tr>
266     <tr>
267       <td>autohide</td>
268       <td>boolean</td>
269       <td>true</td>
270       <td>Auto hide the toast</td>
271     </tr>
272     <tr>
273       <td>delay</td>
274       <td>number</td>
275       <td>
276         <code>500</code>
277       </td>
278       <td>Delay hiding the toast (ms)</td>
279     </tr>
280   </tbody>
281 </table>
282
283 ### Methods
284
285 {% include callout-danger-async-methods.md %}
286
287 #### `$().toast(options)`
288
289 Attaches a toast handler to an element collection.
290
291 #### `.toast('show')`
292
293 Reveals an element's toast. **Returns to the caller before the toast has actually been shown** (i.e. before the `shown.bs.toast` event occurs).
294 You have to manually call this method, instead your toast won't show.
295
296 {% highlight js %}$('#element').toast('show'){% endhighlight %}
297
298 #### `.toast('hide')`
299
300 Hides an element's toast. **Returns to the caller before the toast has actually been hidden** (i.e. before the `hidden.bs.toast` event occurs). You have to manually call this method if you made `autohide` to `false`.
301
302 {% highlight js %}$('#element').toast('hide'){% endhighlight %}
303
304 #### `.toast('dispose')`
305
306 Hides an element's toast. Your toast will remain on the DOM but won't show anymore.
307
308 {% highlight js %}$('#element').toast('dispose'){% endhighlight %}
309
310 ### Events
311
312 <table class="table table-bordered table-striped">
313   <thead>
314     <tr>
315       <th style="width: 150px;">Event Type</th>
316       <th>Description</th>
317     </tr>
318   </thead>
319   <tbody>
320     <tr>
321       <td>show.bs.toast</td>
322       <td>This event fires immediately when the <code>show</code> instance method is called.</td>
323     </tr>
324     <tr>
325       <td>shown.bs.toast</td>
326       <td>This event is fired when the toast has been made visible to the user.</td>
327     </tr>
328     <tr>
329       <td>hide.bs.toast</td>
330       <td>This event is fired immediately when the <code>hide</code> instance method has been called.</td>
331     </tr>
332     <tr>
333       <td>hidden.bs.toast</td>
334       <td>This event is fired when the toast has finished being hidden from the user.</td>
335     </tr>
336   </tbody>
337 </table>
338
339 {% highlight js %}
340 $('#myToast').on('hidden.bs.toast', function () {
341   // do something…
342 })
343 {% endhighlight %}