]>
Commit | Line | Data |
---|---|---|
91e44d91 S |
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>'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'</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 %} |