| commit | author | age | ||
| 83c3f6 | 1 | --- |
| SP | 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 | toc: true | |
| 7 | --- | |
| 8 | ||
| 9 | ## Examples | |
| 10 | ||
| 11 | Alerts are available for any length of text, as well as an optional dismiss button. For proper styling, use one of the eight **required** contextual classes (e.g., `.alert-success`). For inline dismissal, use the [alerts jQuery plugin](#dismissing). | |
| 12 | ||
| 13 | {% capture example %} | |
| 14 | {% for color in site.data.theme-colors %} | |
| 15 | <div class="alert alert-{{ color.name }}" role="alert"> | |
| 16 | A simple {{ color.name }} alert—check it out! | |
| 17 | </div>{% endfor %} | |
| 18 | {% endcapture %} | |
| 19 | {% include example.html content=example %} | |
| 20 | ||
| 21 | {% include callout-warning-color-assistive-technologies.md %} | |
| 22 | ||
| 23 | ### Link color | |
| 24 | ||
| 25 | Use the `.alert-link` utility class to quickly provide matching colored links within any alert. | |
| 26 | ||
| 27 | {% capture example %} | |
| 28 | {% for color in site.data.theme-colors %} | |
| 29 | <div class="alert alert-{{ color.name }}" role="alert"> | |
| 30 | A simple {{ color.name }} alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like. | |
| 31 | </div>{% endfor %} | |
| 32 | {% endcapture %} | |
| 33 | {% include example.html content=example %} | |
| 34 | ||
| 35 | ### Additional content | |
| 36 | ||
| 37 | Alerts can also contain additional HTML elements like headings, paragraphs and dividers. | |
| 38 | ||
| 39 | {% capture example %} | |
| 40 | <div class="alert alert-success" role="alert"> | |
| 41 | <h4 class="alert-heading">Well done!</h4> | |
| 42 | <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> | |
| 43 | <hr> | |
| 44 | <p class="mb-0">Whenever you need to, be sure to use margin utilities to keep things nice and tidy.</p> | |
| 45 | </div> | |
| 46 | {% endcapture %} | |
| 47 | {% include example.html content=example %} | |
| 48 | ||
| 49 | ||
| 50 | ### Dismissing | |
| 51 | ||
| 52 | Using the alert JavaScript plugin, it's possible to dismiss any alert inline. Here's how: | |
| 53 | ||
| 54 | - Be sure you've loaded the alert plugin, or the compiled Bootstrap JavaScript. | |
| 55 | - If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util). The compiled version includes this. | |
| 56 | - Add a dismiss button and the `.alert-dismissible` class, which adds extra padding to the right of the alert and positions the `.close` button. | |
| 57 | - 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. | |
| 58 | - To animate alerts when dismissing them, be sure to add the `.fade` and `.show` classes. | |
| 59 | ||
| 60 | You can see this in action with a live demo: | |
| 61 | ||
| 62 | {% capture example %} | |
| 63 | <div class="alert alert-warning alert-dismissible fade show" role="alert"> | |
| 64 | <strong>Holy guacamole!</strong> You should check in on some of those fields below. | |
| 65 | <button type="button" class="close" data-dismiss="alert" aria-label="Close"> | |
| 66 | <span aria-hidden="true">×</span> | |
| 67 | </button> | |
| 68 | </div> | |
| 69 | {% endcapture %} | |
| 70 | {% include example.html content=example %} | |
| 71 | ||
| 72 | ## JavaScript behavior | |
| 73 | ||
| 74 | ### Triggers | |
| 75 | ||
| 76 | Enable dismissal of an alert via JavaScript: | |
| 77 | ||
| 78 | {% highlight js %} | |
| 79 | $('.alert').alert() | |
| 80 | {% endhighlight %} | |
| 81 | ||
| 82 | Or with `data` attributes on a button **within the alert**, as demonstrated above: | |
| 83 | ||
| 84 | {% highlight html %} | |
| 85 | <button type="button" class="close" data-dismiss="alert" aria-label="Close"> | |
| 86 | <span aria-hidden="true">×</span> | |
| 87 | </button> | |
| 88 | {% endhighlight %} | |
| 89 | ||
| 90 | Note that closing an alert will remove it from the DOM. | |
| 91 | ||
| 92 | ### Methods | |
| 93 | ||
| 94 | | Method | Description | | |
| 95 | | --- | --- | | |
| 96 | | `$().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.) | | |
| 97 | | `$().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. | | |
| 98 | | `$().alert('dispose')` | Destroys an element's alert. | | |
| 99 | ||
| 100 | {% highlight js %}$(".alert").alert('close'){% endhighlight %} | |
| 101 | ||
| 102 | ### Events | |
| 103 | ||
| 104 | Bootstrap's alert plugin exposes a few events for hooking into alert functionality. | |
| 105 | ||
| 106 | | Event | Description | | |
| 107 | | --- | --- | | |
| 108 | | `close.bs.alert` | This event fires immediately when the <code>close</code> instance method is called. | | |
| 109 | | `closed.bs.alert` | This event is fired when the alert has been closed (will wait for CSS transitions to complete). | | |
| 110 | ||
| 111 | {% highlight js %} | |
| 112 | $('#myAlert').on('closed.bs.alert', function () { | |
| 113 | // do something… | |
| 114 | }) | |
| 115 | {% endhighlight %} | |
