src/scss/bootstrap-4.0.0-alpha.6/docs/components/alerts.md

   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">&times;</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">&times;</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 %}