4 description: Documentation and examples for adding Bootstrap popovers to your site.
8 Add small overlay content, like those found in iOS, to any element for housing secondary information.
12 * Will be replaced with the ToC, excluding the "Contents" header
17 Things to know when using the popover plugin:
20 - Popovers 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 popovers to work!
21 - Popovers require the [tooltip plugin]({{ site.baseurl }}/components/tooltips/) as a dependency.
22 - Popovers are opt-in for performance reasons, so **you must initialize them yourself**.
23 - Zero-length `title` and `content` values will never show a popover.
24 - Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc).
25 - Triggering popovers on hidden elements will not work.
26 - Popovers for `.disabled` or `disabled` elements must be triggered on a wrapper element.
27 - When triggered from hyperlinks that span multiple lines, popovers will be centered. Use `white-space: nowrap;` on your `<a>`s to avoid this behavior.
29 Got all that? Great, let's see how they work with some examples.
31 ## Example: Enable popovers everywhere
33 One way to initialize all popovers on a page would be to select them by their `data-toggle` attribute:
37 $('[data-toggle="popover"]').popover()
41 ## Example: Using the `container` option
43 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.
47 $('.example-popover').popover({
55 Four options are available: top, right, bottom, and left aligned.
57 <div class="bd-example bd-example-popover-static">
58 <div class="popover popover-top">
59 <h3 class="popover-title">Popover top</h3>
60 <div class="popover-content">
61 <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
65 <div class="popover popover-right">
66 <h3 class="popover-title">Popover right</h3>
67 <div class="popover-content">
68 <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
72 <div class="popover popover-bottom">
73 <h3 class="popover-title">Popover bottom</h3>
75 <div class="popover-content">
76 <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
80 <div class="popover popover-left">
81 <h3 class="popover-title">Popover left</h3>
82 <div class="popover-content">
83 <p>Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.</p>
87 <div class="clearfix"></div>
93 <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>
98 <div class="bd-example popover-demo">
99 <div class="bd-example-popovers">
100 <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.">
103 <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.">
106 <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.">
109 <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.">
116 <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.">
120 <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.">
124 <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus
125 sagittis lacus vel augue laoreet rutrum faucibus.">
129 <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.">
134 ### Dismiss on next click
136 Use the `focus` trigger to dismiss popovers on the next click that the user makes.
139 #### Specific markup required for dismiss-on-next-click
141 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.
145 <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>
149 $('.popover-dismiss').popover({
158 Enable popovers via JavaScript:
160 {% highlight js %}$('#example').popover(options){% endhighlight %}
164 Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-animation=""`.
166 <table class="table table-bordered table-striped table-responsive">
169 <th style="width: 100px;">Name</th>
170 <th style="width: 100px;">Type</th>
171 <th style="width: 50px;">Default</th>
180 <td>Apply a CSS fade transition to the popover</td>
184 <td>string | false</td>
187 <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>
192 <td>string | element | function</td>
195 <p>Default content value if <code>data-content</code> attribute isn't present.</p>
196 <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>
201 <td>number | object</td>
204 <p>Delay showing and hiding the popover (ms) - does not apply to manual trigger type</p>
205 <p>If a number is supplied, delay is applied to both hide/show</p>
206 <p>Object structure is: <code>delay: { "show": 500, "hide": 100 }</code></p>
213 <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>
217 <td>string | function</td>
220 <p>How to position the popover - top | bottom | left | right.</p>
221 <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>
228 <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>
233 <td><code>'<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-title"></h3><div class="popover-content"></div></div>'</code></td>
235 <p>Base HTML to use when creating the popover.</p>
236 <p>The popover's <code>title</code> will be injected into the <code>.popover-title</code>.</p>
237 <p>The popover's <code>content</code> will be injected into the <code>.popover-content</code>.</p>
238 <p><code>.popover-arrow</code> will become the popover's arrow.</p>
239 <p>The outermost wrapper element should have the <code>.popover</code> class.</p>
244 <td>string | element | function</td>
247 <p>Default title value if <code>title</code> attribute isn't present.</p>
248 <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>
255 <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>
260 <td>'hover focus'</td>
261 <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>
267 <td>Offset of the popover relative to its target. For more information refer to Tether's <a href="http://tether.io/#offset">offset docs</a>.</td>
273 #### Data attributes for individual popovers
275 Options for individual popovers can alternatively be specified through the use of data attributes, as explained above.
280 #### `$().popover(options)`
282 Initializes popovers for an element collection.
284 #### `.popover('show')`
286 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.
288 {% highlight js %}$('#element').popover('show'){% endhighlight %}
290 #### `.popover('hide')`
292 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.
294 {% highlight js %}$('#element').popover('hide'){% endhighlight %}
296 #### `.popover('toggle')`
298 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.
300 {% highlight js %}$('#element').popover('toggle'){% endhighlight %}
302 #### `.popover('dispose')`
304 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.
307 {% highlight js %}$('#element').popover('dispose'){% endhighlight %}
311 <table class="table table-bordered table-striped table-responsive">
314 <th style="width: 150px;">Event Type</th>
320 <td>show.bs.popover</td>
321 <td>This event fires immediately when the <code>show</code> instance method is called.</td>
324 <td>shown.bs.popover</td>
325 <td>This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete).</td>
328 <td>hide.bs.popover</td>
329 <td>This event is fired immediately when the <code>hide</code> instance method has been called.</td>
332 <td>hidden.bs.popover</td>
333 <td>This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete).</td>
339 $('#myPopover').on('hidden.bs.popover', function () {