]>
Commit | Line | Data |
---|---|---|
91e44d91 S |
1 | --- |
2 | layout: docs | |
3 | title: Popovers | |
4 | description: Documentation and examples for adding Bootstrap popovers to your site. | |
5 | group: components | |
6 | --- | |
7 | ||
8 | Add small overlay content, like those found in iOS, to any element for housing secondary information. | |
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 popover plugin: | |
18 | ||
19 | ||
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. | |
28 | ||
29 | Got all that? Great, let's see how they work with some examples. | |
30 | ||
31 | ## Example: Enable popovers everywhere | |
32 | ||
33 | One way to initialize all popovers on a page would be to select them by their `data-toggle` attribute: | |
34 | ||
35 | {% highlight js %} | |
36 | $(function () { | |
37 | $('[data-toggle="popover"]').popover() | |
38 | }) | |
39 | {% endhighlight %} | |
40 | ||
41 | ## Example: Using the `container` option | |
42 | ||
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. | |
44 | ||
45 | {% highlight js %} | |
46 | $(function () { | |
47 | $('.example-popover').popover({ | |
48 | container: 'body' | |
49 | }) | |
50 | }) | |
51 | {% endhighlight %} | |
52 | ||
53 | ## Static popover | |
54 | ||
55 | Four options are available: top, right, bottom, and left aligned. | |
56 | ||
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> | |
62 | </div> | |
63 | </div> | |
64 | ||
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> | |
69 | </div> | |
70 | </div> | |
71 | ||
72 | <div class="popover popover-bottom"> | |
73 | <h3 class="popover-title">Popover bottom</h3> | |
74 | ||
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> | |
77 | </div> | |
78 | </div> | |
79 | ||
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> | |
84 | </div> | |
85 | </div> | |
86 | ||
87 | <div class="clearfix"></div> | |
88 | </div> | |
89 | ||
90 | ## Live demo | |
91 | ||
92 | {% example html %} | |
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> | |
94 | {% endexample %} | |
95 | ||
96 | ### Four directions | |
97 | ||
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."> | |
101 | Popover on top | |
102 | </button> | |
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."> | |
104 | Popover on right | |
105 | </button> | |
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."> | |
107 | Popover on bottom | |
108 | </button> | |
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."> | |
110 | Popover on left | |
111 | </button> | |
112 | </div> | |
113 | </div> | |
114 | ||
115 | {% highlight html %} | |
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."> | |
117 | Popover on top | |
118 | </button> | |
119 | ||
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."> | |
121 | Popover on right | |
122 | </button> | |
123 | ||
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."> | |
126 | Popover on bottom | |
127 | </button> | |
128 | ||
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."> | |
130 | Popover on left | |
131 | </button> | |
132 | {% endhighlight %} | |
133 | ||
134 | ### Dismiss on next click | |
135 | ||
136 | Use the `focus` trigger to dismiss popovers on the next click that the user makes. | |
137 | ||
138 | {% callout danger %} | |
139 | #### Specific markup required for dismiss-on-next-click | |
140 | ||
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. | |
142 | {% endcallout %} | |
143 | ||
144 | {% example html %} | |
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> | |
146 | {% endexample %} | |
147 | ||
148 | {% highlight js %} | |
149 | $('.popover-dismiss').popover({ | |
150 | trigger: 'focus' | |
151 | }) | |
152 | {% endhighlight %} | |
153 | ||
154 | ||
155 | ||
156 | ## Usage | |
157 | ||
158 | Enable popovers via JavaScript: | |
159 | ||
160 | {% highlight js %}$('#example').popover(options){% endhighlight %} | |
161 | ||
162 | ### Options | |
163 | ||
164 | Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-animation=""`. | |
165 | ||
166 | <table class="table table-bordered table-striped table-responsive"> | |
167 | <thead> | |
168 | <tr> | |
169 | <th style="width: 100px;">Name</th> | |
170 | <th style="width: 100px;">Type</th> | |
171 | <th style="width: 50px;">Default</th> | |
172 | <th>Description</th> | |
173 | </tr> | |
174 | </thead> | |
175 | <tbody> | |
176 | <tr> | |
177 | <td>animation</td> | |
178 | <td>boolean</td> | |
179 | <td>true</td> | |
180 | <td>Apply a CSS fade transition to the popover</td> | |
181 | </tr> | |
182 | <tr> | |
183 | <td>container</td> | |
184 | <td>string | false</td> | |
185 | <td>false</td> | |
186 | <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> | |
188 | </td> | |
189 | </tr> | |
190 | <tr> | |
191 | <td>content</td> | |
192 | <td>string | element | function</td> | |
193 | <td>''</td> | |
194 | <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> | |
197 | </td> | |
198 | </tr> | |
199 | <tr> | |
200 | <td>delay</td> | |
201 | <td>number | object</td> | |
202 | <td>0</td> | |
203 | <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> | |
207 | </td> | |
208 | </tr> | |
209 | <tr> | |
210 | <td>html</td> | |
211 | <td>boolean</td> | |
212 | <td>false</td> | |
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> | |
214 | </tr> | |
215 | <tr> | |
216 | <td>placement</td> | |
217 | <td>string | function</td> | |
218 | <td>'right'</td> | |
219 | <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> | |
222 | </td> | |
223 | </tr> | |
224 | <tr> | |
225 | <td>selector</td> | |
226 | <td>string</td> | |
227 | <td>false</td> | |
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> | |
229 | </tr> | |
230 | <tr> | |
231 | <td>template</td> | |
232 | <td>string</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> | |
234 | <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> | |
240 | </td> | |
241 | </tr> | |
242 | <tr> | |
243 | <td>title</td> | |
244 | <td>string | element | function</td> | |
245 | <td>''</td> | |
246 | <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> | |
249 | </td> | |
250 | </tr> | |
251 | <tr> | |
252 | <td>trigger</td> | |
253 | <td>string</td> | |
254 | <td>'click'</td> | |
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> | |
256 | </tr> | |
257 | <tr> | |
258 | <td>constraints</td> | |
259 | <td>Array</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> | |
262 | </tr> | |
263 | <tr> | |
264 | <td>offset</td> | |
265 | <td>string</td> | |
266 | <td>'0 0'</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> | |
268 | </tr> | |
269 | </tbody> | |
270 | </table> | |
271 | ||
272 | {% callout info %} | |
273 | #### Data attributes for individual popovers | |
274 | ||
275 | Options for individual popovers can alternatively be specified through the use of data attributes, as explained above. | |
276 | {% endcallout %} | |
277 | ||
278 | ### Methods | |
279 | ||
280 | #### `$().popover(options)` | |
281 | ||
282 | Initializes popovers for an element collection. | |
283 | ||
284 | #### `.popover('show')` | |
285 | ||
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. | |
287 | ||
288 | {% highlight js %}$('#element').popover('show'){% endhighlight %} | |
289 | ||
290 | #### `.popover('hide')` | |
291 | ||
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. | |
293 | ||
294 | {% highlight js %}$('#element').popover('hide'){% endhighlight %} | |
295 | ||
296 | #### `.popover('toggle')` | |
297 | ||
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. | |
299 | ||
300 | {% highlight js %}$('#element').popover('toggle'){% endhighlight %} | |
301 | ||
302 | #### `.popover('dispose')` | |
303 | ||
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. | |
305 | ||
306 | ||
307 | {% highlight js %}$('#element').popover('dispose'){% endhighlight %} | |
308 | ||
309 | ### Events | |
310 | ||
311 | <table class="table table-bordered table-striped table-responsive"> | |
312 | <thead> | |
313 | <tr> | |
314 | <th style="width: 150px;">Event Type</th> | |
315 | <th>Description</th> | |
316 | </tr> | |
317 | </thead> | |
318 | <tbody> | |
319 | <tr> | |
320 | <td>show.bs.popover</td> | |
321 | <td>This event fires immediately when the <code>show</code> instance method is called.</td> | |
322 | </tr> | |
323 | <tr> | |
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> | |
326 | </tr> | |
327 | <tr> | |
328 | <td>hide.bs.popover</td> | |
329 | <td>This event is fired immediately when the <code>hide</code> instance method has been called.</td> | |
330 | </tr> | |
331 | <tr> | |
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> | |
334 | </tr> | |
335 | </tbody> | |
336 | </table> | |
337 | ||
338 | {% highlight js %} | |
339 | $('#myPopover').on('hidden.bs.popover', function () { | |
340 | // do something… | |
341 | }) | |
342 | {% endhighlight %} |