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

   1 ---
   2 layout: docs
   3 title: Tooltips
   4 description: Documentation and examples for adding custom Bootstrap tooltips with CSS and JavaScript.
   5 group: components
   6 ---
   7
   8 Inspired by the excellent Tipsy jQuery plugin written by Jason Frame. Tooltips are an updated version, which don't rely on images, use CSS3 for animations, and data-attributes for local title storage.
   9
  10 ## Contents
  11
  12 * Will be replaced with the ToC, excluding the "Contents" header
  13 {:toc}
  14
  15 ## Overview
  16
  17 Things to know when using the tooltip plugin:
  18
  19 - Tooltips rely on the 3rd party library [Tether](http://tether.io/) for positioning. You must include [tether.min.js](https://github.com/HubSpot/tether/blob/master/dist/js/tether.min.js) before bootstrap.js in order for tooltips to work!
  20 - Tooltips are opt-in for performance reasons, so **you must initialize them yourself**.
  21 - Tooltips with zero-length titles are never displayed.
  22 - Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc).
  23 - Triggering tooltips on hidden elements will not work.
  24 - Tooltips for `.disabled` or `disabled` elements must be triggered on a wrapper element.
  25 - When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use `white-space: nowrap;` on your `<a>`s to avoid this behavior.
  26
  27 Got all that? Great, let's see how they work with some examples.
  28
  29 ## Example: Enable tooltips everywhere
  30
  31 One way to initialize all tooltips on a page would be to select them by their `data-toggle` attribute:
  32
  33 {% highlight js %}
  34 $(function () {
  35   $('[data-toggle="tooltip"]').tooltip()
  36 })
  37 {% endhighlight %}
  38
  39 ## Examples
  40
  41 Hover over the links below to see tooltips:
  42
  43 <div class="bd-example tooltip-demo">
  44   <p class="muted">Tight pants next level keffiyeh <a href="#" data-toggle="tooltip" title="Default tooltip">you probably</a> haven't heard of them. Photo booth beard raw denim letterpress vegan messenger bag stumptown. Farm-to-table seitan, mcsweeney's fixie sustainable quinoa 8-bit american apparel <a href="#" data-toggle="tooltip" title="Another tooltip">have a</a> terry richardson vinyl chambray. Beard stumptown, cardigans banh mi lomo thundercats. Tofu biodiesel williamsburg marfa, four loko mcsweeney's cleanse vegan chambray. A really ironic artisan <a href="#" data-toggle="tooltip" title="Another one here too">whatever keytar</a>, scenester farm-to-table banksy Austin <a href="#" data-toggle="tooltip" title="The last tip!">twitter handle</a> freegan cred raw denim single-origin coffee viral.
  45   </p>
  46 </div>
  47
  48 ### Static demo
  49
  50 Four options are available: top, right, bottom, and left aligned.
  51
  52 <div class="bd-example bd-example-tooltip-static">
  53   <div class="tooltip tooltip-top" role="tooltip">
  54     <div class="tooltip-inner">
  55       Tooltip on the top
  56     </div>
  57   </div>
  58   <div class="tooltip tooltip-right" role="tooltip">
  59     <div class="tooltip-inner">
  60       Tooltip on the right
  61     </div>
  62   </div>
  63   <div class="tooltip tooltip-bottom" role="tooltip">
  64     <div class="tooltip-inner">
  65       Tooltip on the bottom
  66     </div>
  67   </div>
  68   <div class="tooltip tooltip-left" role="tooltip">
  69     <div class="tooltip-inner">
  70       Tooltip on the left
  71     </div>
  72   </div>
  73 </div>
  74
  75 ### Interactive demo
  76
  77 Hover over the buttons below to see their tooltips.
  78
  79 <div class="bd-example tooltip-demo">
  80   <div class="bd-example-tooltips">
  81     <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">Tooltip on top</button>
  82     <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">Tooltip on right</button>
  83     <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">Tooltip on bottom</button>
  84     <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">Tooltip on left</button>
  85     <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">Tooltip with HTML</button>
  86   </div>
  87 </div>
  88
  89 {% highlight html %}
  90 <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
  91   Tooltip on top
  92 </button>
  93 <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">
  94   Tooltip on right
  95 </button>
  96 <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">
  97   Tooltip on bottom
  98 </button>
  99 <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">
 100   Tooltip on left
 101 </button>
 102 {% endhighlight %}
 103
 104 And with custom HTML added:
 105
 106 {% highlight html %}
 107 <button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
 108   Tooltip with HTML
 109 </button>
 110 {% endhighlight %}
 111
 112 ## Usage
 113
 114 The tooltip plugin generates content and markup on demand, and by default places tooltips after their trigger element.
 115
 116 Trigger the tooltip via JavaScript:
 117
 118 {% highlight js %}
 119 $('#example').tooltip(options)
 120 {% endhighlight %}
 121
 122 ### Markup
 123
 124 The required markup for a tooltip is only a `data` attribute and `title` on the HTML element you wish to have a tooltip. The generated markup of a tooltip is rather simple, though it does require a position (by default, set to `top` by the plugin).
 125
 126 {% callout warning %}
 127 #### Making tooltips work for keyboard and assistive technology users
 128
 129 You should only add tooltips to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). Although arbitrary HTML elements (such as `<span>`s) can be made focusable by adding the `tabindex="0"` attribute, this will add potentially annoying and confusing tab stops on non-interactive elements for keyboard users. In addition, most assistive technologies currently do not announce the tooltip in this situation.
 130 {% endcallout %}
 131
 132 {% highlight html %}
 133 <!-- HTML to write -->
 134 <a href="#" data-toggle="tooltip" title="Some tooltip text!">Hover over me</a>
 135
 136 <!-- Generated markup by the plugin -->
 137 <div class="tooltip tooltip-top" role="tooltip">
 138   <div class="tooltip-arrow"></div>
 139   <div class="tooltip-inner">
 140     Some tooltip text!
 141   </div>
 142 </div>
 143 {% endhighlight %}
 144
 145 ### Options
 146
 147 Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-animation=""`.
 148
 149 <table class="table table-bordered table-striped table-responsive">
 150   <thead>
 151     <tr>
 152       <th style="width: 100px;">Name</th>
 153       <th style="width: 100px;">Type</th>
 154       <th style="width: 50px;">Default</th>
 155       <th>Description</th>
 156     </tr>
 157   </thead>
 158   <tbody>
 159     <tr>
 160       <td>animation</td>
 161       <td>boolean</td>
 162       <td>true</td>
 163       <td>Apply a CSS fade transition to the tooltip</td>
 164     </tr>
 165     <tr>
 166       <td>container</td>
 167       <td>string | element | false</td>
 168       <td>false</td>
 169       <td>
 170         <p>Appends the tooltip to a specific element. Example: <code>container: 'body'</code>. This option is particularly useful in that it allows you to position the tooltip in the flow of the document near the triggering element - which will prevent the tooltip from floating away from the triggering element during a window resize.</p>
 171      </td>
 172     </tr>
 173     <tr>
 174       <td>delay</td>
 175       <td>number | object</td>
 176       <td>0</td>
 177       <td>
 178        <p>Delay showing and hiding the tooltip (ms) - does not apply to manual trigger type</p>
 179        <p>If a number is supplied, delay is applied to both hide/show</p>
 180        <p>Object structure is: <code>delay: { "show": 500, "hide": 100 }</code></p>
 181       </td>
 182     </tr>
 183     <tr>
 184       <td>html</td>
 185       <td>boolean</td>
 186       <td>false</td>
 187       <td>
 188         <p>Allow HTML in the tooltip.</p>
 189         <p>If true, HTML tags in the tooltip's <code>title</code> will be rendered in the tooltip. If false, jQuery's <code>text</code> method will be used to insert content into the DOM.</p>
 190         <p>Use text if you're worried about XSS attacks.</p>
 191       </td>
 192     </tr>
 193     <tr>
 194       <td>placement</td>
 195       <td>string | function</td>
 196       <td>'top'</td>
 197       <td>
 198         <p>How to position the tooltip - top | bottom | left | right.</p>
 199         <p>When a function is used to determine the placement, it is called with the tooltip DOM node as its first argument and the triggering element DOM node as its second. The <code>this</code> context is set to the tooltip instance.</p>
 200       </td>
 201     </tr>
 202     <tr>
 203       <td>selector</td>
 204       <td>string</td>
 205       <td>false</td>
 206       <td>If a selector is provided, tooltip objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have popovers added. See <a href="https://github.com/twbs/bootstrap/issues/4215">this</a> and <a href="https://jsbin.com/zopod/1/edit">an informative example</a>.</td>
 207     </tr>
 208     <tr>
 209       <td>template</td>
 210       <td>string</td>
 211       <td><code>'&lt;div class="tooltip" role="tooltip"&gt;&lt;div class="tooltip-arrow"&gt;&lt;/div&gt;&lt;div class="tooltip-inner"&gt;&lt;/div&gt;&lt;/div&gt;'</code></td>
 212       <td>
 213         <p>Base HTML to use when creating the tooltip.</p>
 214         <p>The tooltip's <code>title</code> will be injected into the <code>.tooltip-inner</code>.</p>
 215         <p><code>.tooltip-arrow</code> will become the tooltip's arrow.</p>
 216         <p>The outermost wrapper element should have the <code>.tooltip</code> class.</p>
 217       </td>
 218     </tr>
 219     <tr>
 220       <td>title</td>
 221       <td>string | element | function</td>
 222       <td>''</td>
 223       <td>
 224         <p>Default title value if <code>title</code> attribute isn't present.</p>
 225         <p>If a function is given, it will be called with its <code>this</code> reference set to the element that the tooltip is attached to.</p>
 226       </td>
 227     </tr>
 228     <tr>
 229       <td>trigger</td>
 230       <td>string</td>
 231       <td>'hover focus'</td>
 232       <td>How tooltip is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. `manual` cannot be combined with any other trigger.</td>
 233     </tr>
 234     <tr>
 235       <td>constraints</td>
 236       <td>Array</td>
 237       <td>[]</td>
 238       <td>An array of constraints - passed through to Tether. For more information refer to Tether's <a href="http://tether.io/#constraints">constraint docs</a>.</td>
 239     </tr>
 240     <tr>
 241       <td>offset</td>
 242       <td>string</td>
 243       <td>'0 0'</td>
 244       <td>Offset of the tooltip relative to its target. For more information refer to Tether's <a href="http://tether.io/#offset">offset docs</a>.</td>
 245     </tr>
 246   </tbody>
 247 </table>
 248
 249 {% callout info %}
 250 #### Data attributes for individual tooltips
 251
 252 Options for individual tooltips can alternatively be specified through the use of data attributes, as explained above.
 253 {% endcallout %}
 254
 255 ### Methods
 256
 257 #### `$().tooltip(options)`
 258
 259 Attaches a tooltip handler to an element collection.
 260
 261 #### `.tooltip('show')`
 262
 263 Reveals an element's tooltip. **Returns to the caller before the tooltip has actually been shown** (i.e. before the `shown.bs.tooltip` event occurs). This is considered a "manual" triggering of the tooltip. Tooltips with zero-length titles are never displayed.
 264
 265 {% highlight js %}$('#element').tooltip('show'){% endhighlight %}
 266
 267 #### `.tooltip('hide')`
 268
 269 Hides an element's tooltip. **Returns to the caller before the tooltip has actually been hidden** (i.e. before the `hidden.bs.tooltip` event occurs). This is considered a "manual" triggering of the tooltip.
 270
 271 {% highlight js %}$('#element').tooltip('hide'){% endhighlight %}
 272
 273 #### `.tooltip('toggle')`
 274
 275 Toggles an element's tooltip. **Returns to the caller before the tooltip has actually been shown or hidden** (i.e. before the `shown.bs.tooltip` or `hidden.bs.tooltip` event occurs). This is considered a "manual" triggering of the tooltip.
 276
 277 {% highlight js %}$('#element').tooltip('toggle'){% endhighlight %}
 278
 279 #### `.tooltip('dispose')`
 280
 281 Hides and destroys an element's tooltip. Tooltips that use delegation (which are created using [the `selector` option](#options)) cannot be individually destroyed on descendant trigger elements.
 282
 283 {% highlight js %}$('#element').tooltip('dispose'){% endhighlight %}
 284
 285 ### Events
 286
 287 <table class="table table-bordered table-striped table-responsive">
 288   <thead>
 289     <tr>
 290       <th style="width: 150px;">Event Type</th>
 291       <th>Description</th>
 292     </tr>
 293   </thead>
 294   <tbody>
 295     <tr>
 296       <td>show.bs.tooltip</td>
 297       <td>This event fires immediately when the <code>show</code> instance method is called.</td>
 298     </tr>
 299     <tr>
 300       <td>shown.bs.tooltip</td>
 301       <td>This event is fired when the tooltip has been made visible to the user (will wait for CSS transitions to complete).</td>
 302     </tr>
 303     <tr>
 304       <td>hide.bs.tooltip</td>
 305       <td>This event is fired immediately when the <code>hide</code> instance method has been called.</td>
 306     </tr>
 307     <tr>
 308       <td>hidden.bs.tooltip</td>
 309       <td>This event is fired when the tooltip has finished being hidden from the user (will wait for CSS transitions to complete).</td>
 310     </tr>
 311   </tbody>
 312 </table>
 313
 314 {% highlight js %}
 315 $('#myTooltip').on('hidden.bs.tooltip', function () {
 316   // do something…
 317 })
 318 {% endhighlight %}