0
0
mirror of https://github.com/twbs/bootstrap.git synced 2024-11-30 12:24:19 +01:00
Bootstrap/docs/4.0/components/tooltips.md

351 lines
15 KiB
Markdown
Raw Normal View History

2014-07-12 11:20:15 +02:00
---
layout: docs
2014-07-12 11:20:15 +02:00
title: Tooltips
2017-05-28 08:01:14 +02:00
description: Documentation and examples for adding custom Bootstrap tooltips with CSS and JavaScript using CSS3 for animations and data-attributes for local title storage.
group: components
2017-05-28 08:01:14 +02:00
toc: true
2014-07-12 11:20:15 +02:00
---
## Overview
2015-08-13 06:12:03 +02:00
Things to know when using the tooltip plugin:
- Tooltips rely on the 3rd party library [Popper.js](https://popper.js.org/) for positioning. You must include [popper.min.js]({{ site.cdn.popper }}) before bootstrap.js or use `bootstrap.bundle.min.js` / `bootstrap.bundle.js` which contains Popper.js in order for tooltips to work!
- If building our JS from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
- Tooltips are opt-in for performance reasons, so **you must initialize them yourself**.
- Tooltips with zero-length titles are never displayed.
- Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc).
- Triggering tooltips on hidden elements will not work.
- Tooltips for `.disabled` or `disabled` elements must be triggered on a wrapper element.
- When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use `white-space: nowrap;` on your `<a>`s to avoid this behavior.
- Tooltips must be hidden before their corresponding elements have been removed from the DOM.
2015-08-09 06:37:48 +02:00
Got all that? Great, let's see how they work with some examples.
2015-08-13 06:12:03 +02:00
## Example: Enable tooltips everywhere
One way to initialize all tooltips on a page would be to select them by their `data-toggle` attribute:
{% highlight js %}
$(function () {
$('[data-toggle="tooltip"]').tooltip()
})
{% endhighlight %}
## Examples
Merge branch 'master' into derp Conflicts: _config.yml dist/css/bootstrap-theme.css.map dist/css/bootstrap.css dist/css/bootstrap.css.map dist/css/bootstrap.min.css docs/_includes/components/glyphicons.html docs/_includes/css/forms.html docs/_includes/css/tables.html docs/_includes/getting-started/browser-device-support.html docs/_includes/header.html docs/_includes/js/affix.html docs/_includes/js/alerts.html docs/_includes/js/buttons.html docs/_includes/js/dropdowns.html docs/_includes/js/overview.html docs/_includes/js/popovers.html docs/_includes/js/tooltips.html docs/_includes/nav/javascript.html docs/assets/css/docs.min.css docs/assets/css/src/docs.css docs/assets/js/customize.min.js docs/assets/js/docs.min.js docs/assets/js/raw-files.min.js docs/browser-bugs.html docs/dist/css/bootstrap-theme.css.map docs/dist/css/bootstrap.css docs/dist/css/bootstrap.css.map docs/dist/css/bootstrap.min.css docs/examples/blog/index.html docs/examples/carousel/index.html docs/examples/cover/index.html docs/examples/dashboard/index.html docs/examples/grid/index.html docs/examples/jumbotron-narrow/index.html docs/examples/jumbotron/index.html docs/examples/justified-nav/index.html docs/examples/navbar-fixed-top/index.html docs/examples/navbar-static-top/index.html docs/examples/navbar/index.html docs/examples/non-responsive/index.html docs/examples/offcanvas/index.html docs/examples/signin/index.html docs/examples/starter-template/index.html docs/examples/sticky-footer-navbar/index.html docs/examples/sticky-footer/index.html docs/examples/theme/index.html docs/examples/tooltip-viewport/index.html less/code.less less/panels.less less/variables.less
2014-08-03 03:30:59 +02:00
2014-07-12 11:34:21 +02:00
Hover over the links below to see tooltips:
2014-03-17 03:03:53 +01:00
<div class="bd-example tooltip-demo">
2014-07-12 11:34:21 +02:00
<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.
</p>
</div>
2014-03-17 03:03:53 +01:00
### Static demo
2014-07-12 11:34:21 +02:00
Four options are available: top, right, bottom, and left aligned.
<div class="bd-example bd-example-tooltip-static">
<div class="tooltip bs-tooltip-top bs-tooltip-top-docs" role="tooltip">
<div class="arrow"></div>
<div class="tooltip-inner">
2015-06-19 08:56:43 +02:00
Tooltip on the top
</div>
</div>
<div class="tooltip bs-tooltip-right bs-tooltip-right-docs" role="tooltip">
<div class="arrow"></div>
<div class="tooltip-inner">
2015-06-19 08:56:43 +02:00
Tooltip on the right
</div>
</div>
<div class="tooltip bs-tooltip-bottom bs-tooltip-bottom-docs" role="tooltip">
<div class="arrow"></div>
<div class="tooltip-inner">
Tooltip on the bottom
</div>
</div>
<div class="tooltip bs-tooltip-left bs-tooltip-left-docs" role="tooltip">
<div class="arrow"></div>
<div class="tooltip-inner">
2015-06-19 08:56:43 +02:00
Tooltip on the left
</div>
</div>
</div>
### Interactive demo
Hover over the buttons below to see their tooltips.
2014-07-12 11:34:21 +02:00
<div class="bd-example tooltip-demo">
<div class="bd-example-tooltips">
2014-07-12 11:34:21 +02:00
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">Tooltip on top</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">Tooltip on right</button>
2015-06-19 08:56:43 +02:00
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">Tooltip on bottom</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">Tooltip on left</button>
<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>
2014-03-17 03:03:53 +01:00
</div>
2014-07-12 11:34:21 +02:00
</div>
{% highlight html %}
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
Tooltip on top
</button>
2015-06-19 08:56:43 +02:00
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">
Tooltip on right
</button>
2014-07-12 11:34:21 +02:00
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">
Tooltip on bottom
</button>
2015-06-19 08:56:43 +02:00
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">
Tooltip on left
2014-07-12 11:34:21 +02:00
</button>
2016-10-10 00:35:52 +02:00
{% endhighlight %}
And with custom HTML added:
{% highlight html %}
<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>
2014-07-12 11:34:21 +02:00
{% endhighlight %}
## Usage
The tooltip plugin generates content and markup on demand, and by default places tooltips after their trigger element.
Trigger the tooltip via JavaScript:
2014-03-17 03:03:53 +01:00
{% highlight js %}
$('#example').tooltip(options)
{% endhighlight %}
2014-07-12 11:34:21 +02:00
### Markup
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).
2015-12-26 21:12:51 +01:00
{% callout warning %}
#### Making tooltips work for keyboard and assistive technology users
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.
{% endcallout %}
2014-06-30 04:58:09 +02:00
{% highlight html %}
2014-03-17 03:03:53 +01:00
<!-- HTML to write -->
<a href="#" data-toggle="tooltip" title="Some tooltip text!">Hover over me</a>
<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
<div class="arrow"></div>
2014-03-17 03:03:53 +01:00
<div class="tooltip-inner">
Some tooltip text!
</div>
</div>
{% endhighlight %}
2014-07-12 11:34:21 +02:00
### Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-animation=""`.
<table class="table table-bordered table-striped table-responsive">
<thead>
<tr>
<th style="width: 100px;">Name</th>
<th style="width: 100px;">Type</th>
<th style="width: 50px;">Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>animation</td>
<td>boolean</td>
<td>true</td>
<td>Apply a CSS fade transition to the tooltip</td>
</tr>
<tr>
<td>container</td>
<td>string | element | false</td>
<td>false</td>
<td>
<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>
</td>
</tr>
<tr>
<td>delay</td>
<td>number | object</td>
<td>0</td>
<td>
<p>Delay showing and hiding the tooltip (ms) - does not apply to manual trigger type</p>
<p>If a number is supplied, delay is applied to both hide/show</p>
<p>Object structure is: <code>delay: { "show": 500, "hide": 100 }</code></p>
</td>
</tr>
<tr>
<td>html</td>
<td>boolean</td>
<td>false</td>
<td>
<p>Allow HTML in the tooltip.</p>
<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>
<p>Use text if you're worried about XSS attacks.</p>
</td>
</tr>
<tr>
<td>placement</td>
<td>string | function</td>
<td>'top'</td>
<td>
<p>How to position the tooltip - auto | top | bottom | left | right.<br>When <code>auto</code> is specified, it will dynamically reorient the tooltip.</p>
<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>
</td>
</tr>
<tr>
<td>selector</td>
<td>string | false</td>
<td>false</td>
<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>
</tr>
<tr>
<td>template</td>
<td>string</td>
<td><code>'&lt;div class="tooltip" role="tooltip"&gt;&lt;div class="arrow"&gt;&lt;/div&gt;&lt;div class="tooltip-inner"&gt;&lt;/div&gt;&lt;/div&gt;'</code></td>
<td>
<p>Base HTML to use when creating the tooltip.</p>
<p>The tooltip's <code>title</code> will be injected into the <code>.tooltip-inner</code>.</p>
<p><code>.arrow</code> will become the tooltip's arrow.</p>
<p>The outermost wrapper element should have the <code>.tooltip</code> class.</p>
</td>
</tr>
<tr>
<td>title</td>
<td>string | element | function</td>
<td>''</td>
<td>
<p>Default title value if <code>title</code> attribute isn't present.</p>
<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>
</td>
</tr>
<tr>
<td>trigger</td>
<td>string</td>
<td>'hover focus'</td>
<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>
</tr>
<tr>
<td>offset</td>
<td>number | string</td>
<td>0</td>
<td>Offset of the tooltip relative to its target. For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..offset.offset">offset docs</a>.</td>
</tr>
<tr>
<td>fallbackPlacement</td>
<td>string | array</td>
<td>'flip'</td>
<td>Allow to specify which position Popper will use on fallback. For more information refer to
Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..flip.behavior">behavior docs</a></td>
</tr>
</tbody>
</table>
2014-07-12 11:34:21 +02:00
{% callout info %}
#### Data attributes for individual tooltips
Options for individual tooltips can alternatively be specified through the use of data attributes, as explained above.
{% endcallout %}
2014-07-12 11:34:21 +02:00
### Methods
{% capture callout-include %}{% include callout-danger-async-methods.md %}{% endcapture %}
{{ callout-include | markdownify }}
#### `$().tooltip(options)`
2014-07-12 11:34:21 +02:00
Attaches a tooltip handler to an element collection.
#### `.tooltip('show')`
2014-07-12 11:34:21 +02:00
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.
2014-07-12 11:34:21 +02:00
{% highlight js %}$('#element').tooltip('show'){% endhighlight %}
#### `.tooltip('hide')`
2014-07-12 11:34:21 +02:00
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.
2014-07-12 11:34:21 +02:00
{% highlight js %}$('#element').tooltip('hide'){% endhighlight %}
#### `.tooltip('toggle')`
2014-07-12 11:34:21 +02:00
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.
2014-07-12 11:34:21 +02:00
{% highlight js %}$('#element').tooltip('toggle'){% endhighlight %}
#### `.tooltip('dispose')`
2014-07-12 11:34:21 +02:00
2015-08-21 07:16:16 +02:00
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.
2014-07-12 11:34:21 +02:00
{% highlight js %}$('#element').tooltip('dispose'){% endhighlight %}
#### `.tooltip('enable')`
Gives an element's tooltip the ability to be shown. **Tooltips are enabled by default.**
{% highlight js %}$('#element').tooltip('enable'){% endhighlight %}
#### `.tooltip('disable')`
Removes the ability for an element's tooltip to be shown. The tooltip will only be able to be shown if it is re-enabled.
{% highlight js %}$('#element').tooltip('disable'){% endhighlight %}
#### `.tooltip('toggleEnabled')`
Toggles the ability for an element's tooltip to be shown or hidden.
{% highlight js %}$('#element').tooltip('toggleEnabled'){% endhighlight %}
2014-07-12 11:34:21 +02:00
#### `.tooltip('update')`
Updates the position of an element's tooltip.
{% highlight js %}$('#element').tooltip('update'){% endhighlight %}
2014-07-12 11:34:21 +02:00
### Events
<table class="table table-bordered table-striped table-responsive">
<thead>
<tr>
<th style="width: 150px;">Event Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>show.bs.tooltip</td>
<td>This event fires immediately when the <code>show</code> instance method is called.</td>
</tr>
<tr>
<td>shown.bs.tooltip</td>
<td>This event is fired when the tooltip has been made visible to the user (will wait for CSS transitions to complete).</td>
</tr>
<tr>
<td>hide.bs.tooltip</td>
<td>This event is fired immediately when the <code>hide</code> instance method has been called.</td>
</tr>
<tr>
<td>hidden.bs.tooltip</td>
<td>This event is fired when the tooltip has finished being hidden from the user (will wait for CSS transitions to complete).</td>
</tr>
<tr>
<td>inserted.bs.tooltip</td>
<td>This event is fired after the <code>show.bs.tooltip</code> event when the tooltip template has been added to the DOM.</td>
</tr>
</tbody>
</table>
2014-03-17 03:03:53 +01:00
{% highlight js %}
$('#myTooltip').on('hidden.bs.tooltip', function () {
// do something…
})
{% endhighlight %}