0
0
mirror of https://github.com/twbs/bootstrap.git synced 2024-12-04 16:24:22 +01:00
Bootstrap/site/docs/4.3/components/popovers.md

380 lines
16 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: Popovers
2017-05-28 08:01:14 +02:00
description: Documentation and examples for adding Bootstrap popovers, like those found in iOS, to any element on your site.
group: components
2017-05-28 08:01:14 +02:00
toc: true
2014-07-12 11:20:15 +02:00
---
## Overview
Things to know when using the popover plugin:
- Popovers 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 popovers to work!
2017-05-29 20:38:06 +02:00
- Popovers require the [tooltip plugin]({{ site.baseurl }}/docs/{{ site.docs_version }}/components/tooltips/) as a dependency.
- If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
- Popovers are opt-in for performance reasons, so **you must initialize them yourself**.
- Zero-length `title` and `content` values will never show a popover.
- Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc).
- Triggering popovers on hidden elements will not work.
- Popovers for `.disabled` or `disabled` elements must be triggered on a wrapper element.
- When triggered from anchors that wrap across multiple lines, popovers will be centered between the anchors' overall width. Use `.text-nowrap` on your `<a>`s to avoid this behavior.
- Popovers must be hidden before their corresponding elements have been removed from the DOM.
- Popovers can be triggered thanks to an element inside a shadow DOM.
{% include callout-info-prefersreducedmotion.md %}
Keep reading to see how popovers work with some examples.
2015-08-09 06:37:48 +02:00
## Example: Enable popovers everywhere
One way to initialize all popovers on a page would be to select them by their `data-toggle` attribute:
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
{% highlight js %}
$(function () {
$('[data-toggle="popover"]').popover()
})
{% endhighlight %}
2014-03-17 03:03:53 +01:00
## Example: Using the `container` option
2015-08-10 05:28:46 +02:00
When you have some styles on a parent element that interfere with a popover, you'll want to specify a custom `container` so that the popover's HTML appears within that element instead.
{% highlight js %}
$(function () {
2015-08-20 20:46:49 +02:00
$('.example-popover').popover({
container: 'body'
2015-08-20 20:46:49 +02:00
})
})
{% endhighlight %}
2017-12-27 06:50:23 +01:00
## Example
2014-07-13 09:54:34 +02:00
2018-03-14 16:44:38 +01:00
{% capture example %}
<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2014-07-13 09:54:34 +02:00
### Four directions
2014-07-13 09:54:34 +02:00
2017-12-27 06:50:23 +01:00
Four options are available: top, right, bottom, and left aligned.
<div class="bd-example popover-demo">
<div class="bd-example-popovers">
2014-07-13 09:54:34 +02:00
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on top
</button>
2015-06-19 08:56:43 +02:00
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on right
</button>
2014-07-13 09:54:34 +02:00
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on bottom
</button>
2015-06-19 08:56:43 +02:00
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on left
2014-07-13 09:54:34 +02:00
</button>
2014-03-17 03:03:53 +01:00
</div>
2014-07-13 09:54:34 +02:00
</div>
2014-03-17 03:03:53 +01:00
{% highlight html %}
2014-07-09 02:14:14 +02:00
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
2014-03-17 03:03:53 +01:00
Popover on top
</button>
2015-06-19 08:56:43 +02:00
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on right
</button>
2014-07-09 02:14:14 +02:00
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus
2014-03-17 03:03:53 +01:00
sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on bottom
</button>
2015-06-19 08:56:43 +02:00
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
Popover on left
2014-03-17 03:03:53 +01:00
</button>
{% endhighlight %}
### Dismiss on next click
2014-07-13 09:54:34 +02:00
Use the `focus` trigger to dismiss popovers on the user's next click of a different element than the toggle element.
2014-07-13 09:54:34 +02:00
{% capture callout %}
#### Specific markup required for dismiss-on-next-click
For proper cross-browser and cross-platform behavior, you must use the `<a>` tag, _not_ the `<button>` tag, and you also must include a [`tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute.
{% endcapture %}
{% include callout.html content=callout type="danger" %}
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
2018-03-14 16:44:38 +01:00
{% capture example %}
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2014-07-13 09:54:34 +02:00
2014-03-17 03:03:53 +01:00
{% highlight js %}
$('.popover-dismiss').popover({
trigger: 'focus'
})
{% endhighlight %}
### Disabled elements
Elements with the `disabled` attribute aren't interactive, meaning users cannot hover or click them to trigger a popover (or tooltip). As a workaround, you'll want to trigger the popover from a wrapper `<div>` or `<span>` and override the `pointer-events` on the disabled element.
For disabled popover triggers, you may also prefer `data-trigger="hover"` so that the popover appears as immediate visual feedback to your users as they may not expect to _click_ on a disabled element.
2018-03-14 16:44:38 +01:00
{% capture example %}
<span class="d-inline-block" data-toggle="popover" data-content="Disabled popover">
<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2014-03-17 03:03:53 +01:00
2014-07-13 09:54:34 +02:00
## Usage
Enable popovers via JavaScript:
{% highlight js %}$('#example').popover(options){% endhighlight %}
### Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-animation=""`.
{% capture callout %}
Note that for security reasons the `sanitize`, `sanitizeFn` and `whiteList` options cannot be supplied using data attributes.
{% endcapture %}
{% include callout.html content=callout type="warning" %}
2017-12-27 22:40:51 +01:00
<table class="table table-bordered table-striped">
<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 popover</td>
</tr>
<tr>
<td>container</td>
<td>string | element | false</td>
<td>false</td>
<td>
<p>Appends the popover to a specific element. Example: <code>container: 'body'</code>. This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize.</p>
</td>
</tr>
<tr>
<td>content</td>
<td>string | element | function</td>
<td>''</td>
<td>
<p>Default content value if <code>data-content</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 popover is attached to.</p>
</td>
</tr>
<tr>
<td>delay</td>
<td>number | object</td>
<td>0</td>
<td>
<p>Delay showing and hiding the popover (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>Insert HTML into the popover. If false, <code>innerText</code> property will be used to insert content into the DOM. Use text if you're worried about XSS attacks.</td>
</tr>
<tr>
<td>placement</td>
<td>string | function</td>
<td>'right'</td>
<td>
<p>How to position the popover - auto | top | bottom | left | right.<br>When <code>auto</code> is specified, it will dynamically reorient the popover.</p>
<p>When a function is used to determine the placement, it is called with the popover DOM node as its first argument and the triggering element DOM node as its second. The <code>this</code> context is set to the popover instance.</p>
</td>
</tr>
<tr>
<td>selector</td>
<td>string | false</td>
<td>false</td>
2019-02-08 09:50:31 +01:00
<td>If a selector is provided, popover 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="{{ site.repo }}/issues/4215">this</a> and <a href="https://codepen.io/Johann-S/pen/djJYPb">an informative example</a>.</td>
</tr>
<tr>
<td>template</td>
<td>string</td>
2019-02-11 11:27:14 +01:00
<td><code>'&lt;div class="popover" role="tooltip"&gt;&lt;div class="popover-arrow"&gt;&lt;/div&gt;&lt;h3 class="popover-header"&gt;&lt;/h3&gt;&lt;div class="popover-body"&gt;&lt;/div&gt;&lt;/div&gt;'</code></td>
<td>
<p>Base HTML to use when creating the popover.</p>
<p>The popover's <code>title</code> will be injected into the <code>.popover-header</code>.</p>
<p>The popover's <code>content</code> will be injected into the <code>.popover-body</code>.</p>
2019-02-11 11:27:14 +01:00
<p><code>.popover-arrow</code> will become the popover's arrow.</p>
<p>The outermost wrapper element should have the <code>.popover</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 popover is attached to.</p>
</td>
</tr>
<tr>
<td>trigger</td>
<td>string</td>
<td>'click'</td>
<td>How popover is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. <code>manual</code> cannot be combined with any other trigger.</td>
</tr>
<tr>
<td>offset</td>
<td>number | string</td>
<td>0</td>
<td>Offset of the popover 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>
<tr>
<td>boundary</td>
<td>string | element</td>
<td>'scrollParent'</td>
<td>Overflow constraint boundary of the popover. Accepts the values of <code>'viewport'</code>, <code>'window'</code>, <code>'scrollParent'</code>, or an HTMLElement reference (JavaScript only). For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..preventOverflow.boundariesElement">preventOverflow docs</a>.</td>
</tr>
<tr>
<td>sanitize</td>
<td>boolean</td>
<td>true</td>
<td>Enable or disable the sanitization. If activated <code>'template'</code>, <code>'content'</code> and <code>'title'</code> options will be sanitized.</td>
</tr>
<tr>
<td>whiteList</td>
<td>object</td>
<td><a href="{{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#sanitizer">Default value</a></td>
<td>Object which contains allowed attributes and tags</td>
</tr>
<tr>
<td>sanitizeFn</td>
<td>null | function</td>
<td>null</td>
<td>Here you can supply your own sanitize function. This can be useful if you prefer to use a dedicated library to perform sanitization.</td>
</tr>
</tbody>
</table>
2014-07-13 09:54:34 +02:00
{% capture callout %}
#### Data attributes for individual popovers
Options for individual popovers can alternatively be specified through the use of data attributes, as explained above.
{% endcapture %}
{% include callout.html content=callout type="info" %}
2014-07-13 09:54:34 +02:00
### Methods
{% include callout-danger-async-methods.md %}
#### `$().popover(options)`
2014-07-13 09:54:34 +02:00
Initializes popovers for an element collection.
#### `.popover('show')`
2014-07-13 09:54:34 +02:00
Reveals an element's popover. **Returns to the caller before the popover has actually been shown** (i.e. before the `shown.bs.popover` event occurs). This is considered a "manual" triggering of the popover. Popovers whose both title and content are zero-length are never displayed.
2014-07-13 09:54:34 +02:00
{% highlight js %}$('#element').popover('show'){% endhighlight %}
#### `.popover('hide')`
2014-07-13 09:54:34 +02:00
Hides an element's popover. **Returns to the caller before the popover has actually been hidden** (i.e. before the `hidden.bs.popover` event occurs). This is considered a "manual" triggering of the popover.
2014-07-13 09:54:34 +02:00
{% highlight js %}$('#element').popover('hide'){% endhighlight %}
#### `.popover('toggle')`
2014-07-13 09:54:34 +02:00
Toggles an element's popover. **Returns to the caller before the popover has actually been shown or hidden** (i.e. before the `shown.bs.popover` or `hidden.bs.popover` event occurs). This is considered a "manual" triggering of the popover.
2014-07-13 09:54:34 +02:00
{% highlight js %}$('#element').popover('toggle'){% endhighlight %}
#### `.popover('dispose')`
2014-07-13 09:54:34 +02:00
Hides and destroys an element's popover. Popovers that use delegation (which are created using [the `selector` option](#options)) cannot be individually destroyed on descendant trigger elements.
Merge branch 'master' into v4 Conflicts: .travis.yml Gruntfile.js bower.json dist/css/bootstrap.css dist/css/bootstrap.css.map dist/css/bootstrap.min.css dist/js/bootstrap.js dist/js/bootstrap.min.js docs/_data/glyphicons.yml docs/_includes/components/breadcrumbs.html docs/_includes/components/button-dropdowns.html docs/_includes/components/button-groups.html docs/_includes/components/dropdowns.html docs/_includes/components/glyphicons.html docs/_includes/components/labels.html docs/_includes/components/list-group.html docs/_includes/components/media.html docs/_includes/components/navs.html docs/_includes/components/panels.html docs/_includes/components/progress-bars.html docs/_includes/components/thumbnails.html docs/_includes/components/wells.html docs/_includes/css/buttons.html docs/_includes/css/forms.html docs/_includes/css/helpers.html docs/_includes/css/images.html docs/_includes/css/less.html docs/_includes/customizer-variables.html docs/_includes/getting-started/accessibility.html docs/_includes/getting-started/browser-device-support.html docs/_includes/getting-started/community.html docs/_includes/getting-started/examples.html docs/_includes/getting-started/grunt.html docs/_includes/getting-started/license.html docs/_includes/getting-started/template.html docs/_includes/header.html docs/_includes/js/affix.html docs/_includes/js/alerts.html docs/_includes/js/carousel.html docs/_includes/js/collapse.html docs/_includes/js/dropdowns.html docs/_includes/js/modal.html docs/_includes/js/overview.html docs/_includes/js/popovers.html docs/_includes/js/scrollspy.html docs/_includes/js/tabs.html docs/_includes/js/tooltips.html docs/_includes/js/transitions.html docs/_includes/nav/javascript.html docs/_layouts/default.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/assets/js/vendor/FileSaver.js docs/assets/js/vendor/autoprefixer.js docs/assets/js/vendor/uglify.min.js docs/dist/css/bootstrap.css docs/dist/css/bootstrap.css.map docs/dist/css/bootstrap.min.css docs/dist/js/bootstrap.min.js docs/examples/blog/index.html docs/examples/carousel/index.html docs/examples/cover/index.html docs/examples/dashboard/index.html docs/examples/narrow-jumbotron/narrow-jumbotron.css docs/examples/navbar-fixed-top/index.html docs/examples/navbar-static-top/index.html docs/examples/non-responsive/index.html docs/examples/non-responsive/non-responsive.css docs/examples/theme/index.html grunt/configBridge.json js/affix.js js/carousel.js js/collapse.js js/dropdown.js js/modal.js js/popover.js js/scrollspy.js js/tab.js js/tests/unit/affix.js js/tests/unit/button.js js/tests/unit/carousel.js js/tests/unit/modal.js js/tests/unit/tooltip.js js/tooltip.js less/badges.less less/glyphicons.less less/type.less less/variables.less package.json scss/_dropdown.scss scss/_forms.scss test-infra/npm-shrinkwrap.json
2015-03-01 22:44:10 +01:00
{% highlight js %}$('#element').popover('dispose'){% endhighlight %}
#### `.popover('enable')`
Gives an element's popover the ability to be shown. **Popovers are enabled by default.**
{% highlight js %}$('#element').popover('enable'){% endhighlight %}
#### `.popover('disable')`
Removes the ability for an element's popover to be shown. The popover will only be able to be shown if it is re-enabled.
{% highlight js %}$('#element').popover('disable'){% endhighlight %}
#### `.popover('toggleEnabled')`
Toggles the ability for an element's popover to be shown or hidden.
{% highlight js %}$('#element').popover('toggleEnabled'){% endhighlight %}
2014-07-13 09:54:34 +02:00
#### `.popover('update')`
Updates the position of an element's popover.
{% highlight js %}$('#element').popover('update'){% endhighlight %}
2014-07-13 09:54:34 +02:00
### Events
2017-12-27 22:40:51 +01:00
<table class="table table-bordered table-striped">
<thead>
<tr>
<th style="width: 150px;">Event Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>show.bs.popover</td>
<td>This event fires immediately when the <code>show</code> instance method is called.</td>
</tr>
<tr>
<td>shown.bs.popover</td>
<td>This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete).</td>
</tr>
<tr>
<td>hide.bs.popover</td>
<td>This event is fired immediately when the <code>hide</code> instance method has been called.</td>
</tr>
<tr>
<td>hidden.bs.popover</td>
<td>This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete).</td>
</tr>
<tr>
<td>inserted.bs.popover</td>
<td>This event is fired after the <code>show.bs.popover</code> event when the popover template has been added to the DOM.</td>
</tr>
</tbody>
</table>
2014-03-17 03:03:53 +01:00
{% highlight js %}
$('#myPopover').on('hidden.bs.popover', function () {
2019-02-10 21:25:51 +01:00
// do something...
2014-03-17 03:03:53 +01:00
})
{% endhighlight %}