]>
Commit | Line | Data |
---|---|---|
91e44d91 S |
1 | --- |
2 | layout: docs | |
3 | title: Alerts | |
4 | description: Provide contextual feedback messages for typical user actions with the handful of available and flexible alert messages. | |
5 | group: components | |
6 | --- | |
7 | ||
8 | Provide contextual feedback messages for typical user actions with the handful of available and flexible alert messages. | |
9 | ||
10 | ## Contents | |
11 | ||
12 | * Will be replaced with the ToC, excluding the "Contents" header | |
13 | {:toc} | |
14 | ||
15 | ## Examples | |
16 | ||
17 | Alerts are available for any length of text, as well as an optional dismiss button. For proper styling, use one of the four **required** contextual classes (e.g., `.alert-success`). For inline dismissal, use the [alerts jQuery plugin](#dismissing). | |
18 | ||
19 | {% example html %} | |
20 | <div class="alert alert-success" role="alert"> | |
21 | <strong>Well done!</strong> You successfully read this important alert message. | |
22 | </div> | |
23 | <div class="alert alert-info" role="alert"> | |
24 | <strong>Heads up!</strong> This alert needs your attention, but it's not super important. | |
25 | </div> | |
26 | <div class="alert alert-warning" role="alert"> | |
27 | <strong>Warning!</strong> Better check yourself, you're not looking too good. | |
28 | </div> | |
29 | <div class="alert alert-danger" role="alert"> | |
30 | <strong>Oh snap!</strong> Change a few things up and try submitting again. | |
31 | </div> | |
32 | {% endexample %} | |
33 | ||
34 | {% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %} | |
35 | {{ callout-include | markdownify }} | |
36 | ||
37 | ### Link color | |
38 | ||
39 | Use the `.alert-link` utility class to quickly provide matching colored links within any alert. | |
40 | ||
41 | {% example html %} | |
42 | <div class="alert alert-success" role="alert"> | |
43 | <strong>Well done!</strong> You successfully read <a href="#" class="alert-link">this important alert message</a>. | |
44 | </div> | |
45 | <div class="alert alert-info" role="alert"> | |
46 | <strong>Heads up!</strong> This <a href="#" class="alert-link">alert needs your attention</a>, but it's not super important. | |
47 | </div> | |
48 | <div class="alert alert-warning" role="alert"> | |
49 | <strong>Warning!</strong> Better check yourself, you're <a href="#" class="alert-link">not looking too good</a>. | |
50 | </div> | |
51 | <div class="alert alert-danger" role="alert"> | |
52 | <strong>Oh snap!</strong> <a href="#" class="alert-link">Change a few things up</a> and try submitting again. | |
53 | </div> | |
54 | {% endexample %} | |
55 | ||
56 | ### Additional content | |
57 | ||
58 | Alerts can also contain additional HTML elements like headings and paragraphs. | |
59 | ||
60 | {% example html %} | |
61 | <div class="alert alert-success" role="alert"> | |
62 | <h4 class="alert-heading">Well done!</h4> | |
63 | <p>Aww yeah, you successfully read this important alert message. This example text is going to run a bit longer so that you can see how spacing within an alert works with this kind of content.</p> | |
64 | <p class="mb-0">Whenever you need to, be sure to use margin utilities to keep things nice and tidy.</p> | |
65 | </div> | |
66 | {% endexample %} | |
67 | ||
68 | ||
69 | ### Dismissing | |
70 | ||
71 | Using the alert JavaScript plugin, it's possible to dismiss any alert inline. Here's how: | |
72 | ||
73 | - Be sure you've loaded the alert plugin, or the compiled Bootstrap JavaScript. | |
74 | - Add a dismiss button and the `.alert-dismissible` class, which adds extra padding to the right of the alert and positions the `.close` button. | |
75 | - On the dismiss button, add the `data-dismiss="alert"` attribute, which triggers the JavaScript functionality. Be sure to use the `<button>` element with it for proper behavior across all devices. | |
76 | - To animate alerts when dismissing them, be sure to add the `.fade` and `.show` classes. | |
77 | ||
78 | You can see this in action with a live demo: | |
79 | ||
80 | {% example html %} | |
81 | <div class="alert alert-warning alert-dismissible fade show" role="alert"> | |
82 | <button type="button" class="close" data-dismiss="alert" aria-label="Close"> | |
83 | <span aria-hidden="true">×</span> | |
84 | </button> | |
85 | <strong>Holy guacamole!</strong> You should check in on some of those fields below. | |
86 | </div> | |
87 | {% endexample %} | |
88 | ||
89 | ## JavaScript behavior | |
90 | ||
91 | ### Triggers | |
92 | ||
93 | Enable dismissal of an alert via JavaScript: | |
94 | ||
95 | {% highlight js %} | |
96 | $(".alert").alert() | |
97 | {% endhighlight %} | |
98 | ||
99 | Or with `data` attributes on a button **within the alert**, as demonstrated above: | |
100 | ||
101 | {% highlight html %} | |
102 | <button type="button" class="close" data-dismiss="alert" aria-label="Close"> | |
103 | <span aria-hidden="true">×</span> | |
104 | </button> | |
105 | {% endhighlight %} | |
106 | ||
107 | Note that closing an alert will remove it from the DOM. | |
108 | ||
109 | ### Methods | |
110 | ||
111 | | Method | Description | | |
112 | | --- | --- | | |
113 | | `$().alert()` | Makes an alert listen for click events on descendant elements which have the `data-dismiss="alert"` attribute. (Not necessary when using the data-api's auto-initialization.) | | |
114 | | `$().alert('close')` | Closes an alert by removing it from the DOM. If the `.fade` and `.show` classes are present on the element, the alert will fade out before it is removed. | | |
115 | ||
116 | {% highlight js %}$(".alert").alert('close'){% endhighlight %} | |
117 | ||
118 | ### Events | |
119 | ||
120 | Bootstrap's alert plugin exposes a few events for hooking into alert functionality. | |
121 | ||
122 | | Event | Description | | |
123 | | --- | --- | | |
124 | | `close.bs.alert` | This event fires immediately when the <code>close</code> instance method is called. | | |
125 | | `closed.bs.alert` | This event is fired when the alert has been closed (will wait for CSS transitions to complete). | | |
126 | ||
127 | {% highlight js %} | |
128 | $('#myAlert').on('closed.bs.alert', function () { | |
129 | // do something… | |
130 | }) | |
131 | {% endhighlight %} |