mirror of
https://github.com/twbs/bootstrap.git
synced 2024-12-12 00:08:59 +01:00
372 lines
15 KiB
Markdown
372 lines
15 KiB
Markdown
---
|
||
layout: docs
|
||
title: Popovers
|
||
description: Documentation and examples for adding Bootstrap popovers, like those found in iOS, to any element on your site.
|
||
group: components
|
||
toc: true
|
||
---
|
||
|
||
## 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!
|
||
- Popovers require the [tooltip plugin]({{ site.baseurl }}/docs/{{ site.docs_version }}/components/tooltips/) as a dependency.
|
||
- If building our JS 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 hyperlinks that span multiple lines, popovers will be centered. Use `white-space: nowrap;` on your `<a>`s to avoid this behavior.
|
||
- Popovers must be hidden before their corresponding elements have been removed from the DOM.
|
||
|
||
Got all that? Great, let's see how they work with some examples.
|
||
|
||
## Example: Enable popovers everywhere
|
||
|
||
One way to initialize all popovers on a page would be to select them by their `data-toggle` attribute:
|
||
|
||
{% highlight js %}
|
||
$(function () {
|
||
$('[data-toggle="popover"]').popover()
|
||
})
|
||
{% endhighlight %}
|
||
|
||
## Example: Using the `container` option
|
||
|
||
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 () {
|
||
$('.example-popover').popover({
|
||
container: 'body'
|
||
})
|
||
})
|
||
{% endhighlight %}
|
||
|
||
## Static popover
|
||
|
||
Four options are available: top, right, bottom, and left aligned.
|
||
|
||
<div class="bd-example bd-example-popover-static">
|
||
<div class="popover bs-popover-top bs-popover-top-docs">
|
||
<div class="arrow"></div>
|
||
<h3 class="popover-header">Popover top</h3>
|
||
<div class="popover-body">
|
||
<p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="popover bs-popover-right bs-popover-right-docs">
|
||
<div class="arrow"></div>
|
||
<h3 class="popover-header">Popover right</h3>
|
||
<div class="popover-body">
|
||
<p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="popover bs-popover-bottom bs-popover-bottom-docs">
|
||
<div class="arrow"></div>
|
||
<h3 class="popover-header">Popover bottom</h3>
|
||
<div class="popover-body">
|
||
<p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="popover bs-popover-left bs-popover-left-docs">
|
||
<div class="arrow"></div>
|
||
<h3 class="popover-header">Popover left</h3>
|
||
<div class="popover-body">
|
||
<p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="clearfix"></div>
|
||
</div>
|
||
|
||
## Live demo
|
||
|
||
{% example html %}
|
||
<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>
|
||
{% endexample %}
|
||
|
||
### Four directions
|
||
|
||
<div class="bd-example popover-demo">
|
||
<div class="bd-example-popovers">
|
||
<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>
|
||
<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>
|
||
<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>
|
||
<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
|
||
</button>
|
||
</div>
|
||
</div>
|
||
|
||
{% highlight html %}
|
||
<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>
|
||
|
||
<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>
|
||
|
||
<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>
|
||
|
||
<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
|
||
</button>
|
||
{% endhighlight %}
|
||
|
||
### Dismiss on next click
|
||
|
||
Use the `focus` trigger to dismiss popovers on the next click that the user makes.
|
||
|
||
{% callout danger %}
|
||
#### 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.
|
||
{% endcallout %}
|
||
|
||
{% example html %}
|
||
<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>
|
||
{% endexample %}
|
||
|
||
{% highlight js %}
|
||
$('.popover-dismiss').popover({
|
||
trigger: 'focus'
|
||
})
|
||
{% endhighlight %}
|
||
|
||
|
||
## 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=""`.
|
||
|
||
<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 popover</td>
|
||
</tr>
|
||
<tr>
|
||
<td>container</td>
|
||
<td>string | 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, jQuery's <code>text</code> method 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</td>
|
||
<td>false</td>
|
||
<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="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>'<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'</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>
|
||
<p><code>.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. `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 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>
|
||
</tbody>
|
||
</table>
|
||
|
||
{% callout info %}
|
||
#### Data attributes for individual popovers
|
||
|
||
Options for individual popovers can alternatively be specified through the use of data attributes, as explained above.
|
||
{% endcallout %}
|
||
|
||
### Methods
|
||
|
||
{% capture callout-include %}{% include callout-danger-async-methods.md %}{% endcapture %}
|
||
{{ callout-include | markdownify }}
|
||
|
||
#### `$().popover(options)`
|
||
|
||
Initializes popovers for an element collection.
|
||
|
||
#### `.popover('show')`
|
||
|
||
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.
|
||
|
||
{% highlight js %}$('#element').popover('show'){% endhighlight %}
|
||
|
||
#### `.popover('hide')`
|
||
|
||
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.
|
||
|
||
{% highlight js %}$('#element').popover('hide'){% endhighlight %}
|
||
|
||
#### `.popover('toggle')`
|
||
|
||
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.
|
||
|
||
{% highlight js %}$('#element').popover('toggle'){% endhighlight %}
|
||
|
||
#### `.popover('dispose')`
|
||
|
||
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.
|
||
|
||
{% 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 %}
|
||
|
||
#### `.popover('update')`
|
||
|
||
Updates the position of an element's popover.
|
||
|
||
{% highlight js %}$('#element').popover('update'){% endhighlight %}
|
||
|
||
### 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.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>
|
||
|
||
{% highlight js %}
|
||
$('#myPopover').on('hidden.bs.popover', function () {
|
||
// do something…
|
||
})
|
||
{% endhighlight %}
|