1 | # Tooltips
|
2 |
|
3 | > Easily add tooltips to elements or components via the `<b-tooltip>` component or
|
4 | > [`v-b-tooltip`](/docs/directives/tooltip) directive (preferred method).
|
5 |
|
6 | ```html
|
7 | <div class="text-center my-3">
|
8 | <b-button v-b-tooltip.hover title="Tooltip content">Hover Me</b-button>
|
9 | </div>
|
10 |
|
11 | <!-- b-tooltip.vue -->
|
12 | ```
|
13 |
|
14 | ## Overview
|
15 |
|
16 | Things to know when using tooltip component:
|
17 |
|
18 | - Tooltips rely on the 3rd party library Popper.js for positioning. The library is bundled with
|
19 | BootstrapVue in the dist files!
|
20 | - Tooltips with zero-length titles are never displayed.
|
21 | - Triggering tooltips on hidden elements will not work.
|
22 | - Specify `container` as `null` (default, appends to `<body>`) to avoid rendering problems in more
|
23 | complex components (like input groups, button groups, etc). You can use container to optionally
|
24 | specify a different element to append the rendered tooltip to.
|
25 | - Tooltips for `disabled` elements must be triggered on a wrapper element.
|
26 | - When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use
|
27 | white-space: nowrap; on your `<a>`s, `<b-link>`s and `<router-link>`s to avoid this behavior.
|
28 | - Tooltips must be hidden before their corresponding elements have been removed from the DOM.
|
29 |
|
30 | The `<b-tooltip>` component inserts a hidden (`display:none`) `<div>` intermediate container element
|
31 | at the point in the DOM where the `<b-tooltip>` component is placed. This may affect layout and/or
|
32 | styling of components such as `<b-button-group>`, `<b-button-toolbar>`, and `<b-input-group>`. To
|
33 | avoid these possible layout issues, place the `<b-tooltip>` component **outside** of these types of
|
34 | components.
|
35 |
|
36 | The target element **must** exist in the document before `<b-tooltip>` is mounted. If the target
|
37 | element is not found during mount, the tooltip will never open. Always place your `<b-tooltip>`
|
38 | component lower in the DOM than your target element. This rule also applies if a callback is used as
|
39 | target element, since that callback is called only once on mount.
|
40 |
|
41 | **Note:** _When using the default slot for the title, `<b-tooltip>` transfers the rendered DOM from
|
42 | that slot into the tooltip's markup when shown, and returns the content back to the `<b-tooltip>`
|
43 | component when hidden. This may cause some issues in rare circumstances, so please test your
|
44 | implementation accordingly! The `title` prop does not have this behavior. For simple tooltips, we
|
45 | recommend using the `v-b-tooltip` directive and enable the `html` modifier if needed._
|
46 |
|
47 | ## Positioning
|
48 |
|
49 | Twelve options are available for positioning: `top`, `topleft`, `topright`, `right`, `righttop`,
|
50 | `rightbottom`, `bottom`, `bottomleft`, `bottomright`, `left`, `lefttop`, and `leftbottom` aligned.
|
51 | The default position is `top`. Positioning is relative to the trigger element.
|
52 |
|
53 | <div class="bd-example bd-example-tooltip-static">
|
54 | <div class="tooltip bs-tooltip-top bs-tooltip-top-docs" role="tooltip">
|
55 | <div class="arrow" style="left: 6px"></div>
|
56 | <div class="tooltip-inner">Tooltip on the top</div>
|
57 | </div>
|
58 | <div class="tooltip bs-tooltip-top bs-tooltip-top-docs" role="tooltip">
|
59 | <div class="arrow" style="right: 6px"></div>
|
60 | <div class="tooltip-inner">Tooltip on the topleft</div>
|
61 | </div>
|
62 | <div class="tooltip bs-tooltip-top bs-tooltip-top-docs" role="tooltip">
|
63 | <div class="arrow" style="left: 6px"></div>
|
64 | <div class="tooltip-inner">Tooltip on the topright</div>
|
65 | </div>
|
66 | <div class="tooltip bs-tooltip-right bs-tooltip-right-docs" role="tooltip">
|
67 | <div class="arrow" style="top: 4px"></div>
|
68 | <div class="tooltip-inner">Tooltip on the right</div>
|
69 | </div>
|
70 | <div class="tooltip bs-tooltip-right bs-tooltip-right-docs" role="tooltip">
|
71 | <div class="arrow" style="bottom: 4px"></div>
|
72 | <div class="tooltip-inner">Tooltip on the righttop</div>
|
73 | </div>
|
74 | <div class="tooltip bs-tooltip-right bs-tooltip-right-docs" role="tooltip">
|
75 | <div class="arrow" style="top: 4px"></div>
|
76 | <div class="tooltip-inner">Tooltip on the rightbottom</div>
|
77 | </div>
|
78 | <div class="tooltip bs-tooltip-bottom bs-tooltip-bottom-docs" role="tooltip">
|
79 | <div class="arrow" style="left: 6px"></div>
|
80 | <div class="tooltip-inner">Tooltip on the bottom</div>
|
81 | </div>
|
82 | <div class="tooltip bs-tooltip-bottom bs-tooltip-bottom-docs" role="tooltip">
|
83 | <div class="arrow" style="right: 6px"></div>
|
84 | <div class="tooltip-inner">Tooltip on the bottomleft</div>
|
85 | </div>
|
86 | <div class="tooltip bs-tooltip-bottom bs-tooltip-bottom-docs" role="tooltip">
|
87 | <div class="arrow" style="left: 6px"></div>
|
88 | <div class="tooltip-inner">Tooltip on the bottomright</div>
|
89 | </div>
|
90 | <div class="tooltip bs-tooltip-left bs-tooltip-left-docs" role="tooltip">
|
91 | <div class="arrow" style="top: 4px"></div>
|
92 | <div class="tooltip-inner">Tooltip on the left</div>
|
93 | </div>
|
94 | <div class="tooltip bs-tooltip-left bs-tooltip-left-docs" role="tooltip">
|
95 | <div class="arrow" style="bottom: 4px"></div>
|
96 | <div class="tooltip-inner">Tooltip on the lefttop</div>
|
97 | </div>
|
98 | <div class="tooltip bs-tooltip-left bs-tooltip-left-docs" role="tooltip">
|
99 | <div class="arrow" style="top: 4px"></div>
|
100 | <div class="tooltip-inner">Tooltip on the leftbottom</div>
|
101 | </div>
|
102 | </div>
|
103 |
|
104 | ## Triggers
|
105 |
|
106 | Tooltips can be triggered (opened/closed) via any combination of `click`, `hover` and `focus`. The
|
107 | default trigger is `hover focus`.
|
108 |
|
109 | If a tooltip has more than one trigger, then all triggers must be cleared before the tooltip will
|
110 | close. I.e. if a tooltip has the trigger `focus click`, and it was opened by `focus`, and the user
|
111 | then clicks the trigger element, they must click it again **and** move focus to close the tooltip.
|
112 |
|
113 | ## `<b-tooltip>` component usage
|
114 |
|
115 | ```html
|
116 | <b-container fluid>
|
117 | <b-row>
|
118 | <b-col md="4" class="py-4">
|
119 | <b-button id="button-1" variant="outline-success">Live chat</b-button>
|
120 | </b-col>
|
121 | <b-col md="4" class="py-4">
|
122 | <b-button id="button-2" variant="outline-success">Html chat</b-button>
|
123 | </b-col>
|
124 | <b-col md="4" class="py-4">
|
125 | <b-button ref="button-3" variant="outline-success">Alternative chat</b-button>
|
126 | </b-col>
|
127 | </b-row>
|
128 |
|
129 | <!-- Tooltip title specified via prop title -->
|
130 | <b-tooltip target="button-1" title="Online!"></b-tooltip>
|
131 |
|
132 | <!-- HTML title specified via default slot -->
|
133 | <b-tooltip target="button-2" placement="bottom">
|
134 | Hello <strong>World!</strong>
|
135 | </b-tooltip>
|
136 |
|
137 | <!-- Tooltip for an element identified by ref -->
|
138 | <b-tooltip :target="() => $refs['button-3']" title="Alternative!"></b-tooltip>
|
139 | </b-container>
|
140 |
|
141 | <!-- b-tooltip-component.vue -->
|
142 | ```
|
143 |
|
144 | ### Component options
|
145 |
|
146 | | Prop | Default | Description | Supported values |
|
147 | | -------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
148 | | `target` | `null` | Element String ID, or a reference to an element or component, or a function returning either of them, that you want to trigger the tooltip. **Required** | Any valid, in-document unique element ID, element reference or component reference or a function returning any such ID / reference |
|
149 | | `title` | `null` | Tooltip content (text only, no HTML). if HTML is required, place it in the default slot | Plain text |
|
150 | | `placement` | `'top'` | Tooltip position, relative to the trigger element. | `top`, `bottom`, `left`, `right`, `auto`, `topleft`, `topright`, `bottomleft`, `bottomright`, `lefttop`, `leftbottom`, `righttop`, `rightbottom` |
|
151 | | `fallback-placement` | `'flip'` | Auto-flip placement behaviour of the tooltip, relative to the trigger element. | `flip`, `clockwise`, `counterclockwise`, or an array of valid placements evaluated from left to right |
|
152 | | `triggers` | `'hover focus'` | Space separated list of event(s), which will trigger open/close of tooltip | `hover`, `focus`, `click`. Note `blur` is a special use case to close tooltip on next click, usually used in conjunction with `click`. |
|
153 | | `no-fade` | `false` | Disable fade animation when set to `true` | `true` or `false` |
|
154 | | `delay` | `0` | Delay showing and hiding of tooltip by specified number of milliseconds. Can also be specified as an object in the form of `{ show: 100, hide: 400 }` allowing different show and hide delays | `0` and up, integers only. |
|
155 | | `offset` | `0` | Shift the center of the tooltip by specified number of pixels | Any negative or positive integer |
|
156 | | `container` | `null` | Element string ID to append rendered tooltip into. If `null` or element not found, tooltip is appended to `<body>` (default) | Any valid in-document unique element ID. |
|
157 | | `boundary` | `'scrollParent'` | The container that the tooltip will be constrained visually. The default should suffice in most cases, but you may need to change this if your target element is in a small container with overflow scroll | `'scrollParent'` (default), `'viewport'`, `'window'`, or a reference to an HTML element. |
|
158 | | `boundary-padding` | `5` | Amount of pixel used to define a minimum distance between the boundaries and the tooltip. This makes sure the tooltip always has a little padding between the edges of its container. | Any positive number |
|
159 |
|
160 | ### Programmatically show and hide tooltip
|
161 |
|
162 | You can manually control the visibility of a tooltip via the syncable Boolean `show` prop. Setting
|
163 | it to `true` will show the tooltip, while setting it to `false` will hide the tooltip.
|
164 |
|
165 | ```html
|
166 | <template>
|
167 | <div class="text-center">
|
168 | <div>
|
169 | <b-button id="tooltip-button-1" variant="primary">I have a tooltip</b-button>
|
170 | </div>
|
171 |
|
172 | <div class="mt-3">
|
173 | <b-button @click="show = !show">Toggle Tooltip</b-button>
|
174 | </div>
|
175 |
|
176 | <b-tooltip :show.sync="show" target="tooltip-button-1" placement="top">
|
177 | Hello <strong>World!</strong>
|
178 | </b-tooltip>
|
179 | </div>
|
180 | </template>
|
181 | <script>
|
182 | export default {
|
183 | data: {
|
184 | show: true
|
185 | }
|
186 | }
|
187 | </script>
|
188 |
|
189 | <!-- b-tooltip-show-sync.vue -->
|
190 | ```
|
191 |
|
192 | To make the tooltip shown on initial render, simply add the `show` prop on `<b-tooltip>`:
|
193 |
|
194 | ```html
|
195 | <div class="text-center">
|
196 | <b-button id="tooltip-button-2" variant="primary">Button</b-button>
|
197 | <b-tooltip show target="tooltip-button-2">I start open</b-tooltip>
|
198 | </div>
|
199 |
|
200 | <!-- b-tooltip-show-open.vue -->
|
201 | ```
|
202 |
|
203 | Programmatic control can also be affected by submitting `'open'` and `'close'` events to the tooltip
|
204 | by reference.
|
205 |
|
206 | ```html
|
207 | <template>
|
208 | <div class="d-flex flex-column text-md-center">
|
209 | <div class="p-2">
|
210 | <b-button id="tooltip-button-show-event" variant="primary">I have a tooltip</b-button>
|
211 | </div>
|
212 |
|
213 | <div class="p-2">
|
214 | <b-button class="px-1" @click="onOpen">Open</b-button>
|
215 | <b-button class="px-1" @click="onClose">Close</b-button>
|
216 | </div>
|
217 |
|
218 | <b-tooltip ref="tooltip" target="tooltip-button-show-event">
|
219 | Hello <strong>World!</strong>
|
220 | </b-tooltip>
|
221 | </div>
|
222 | </template>
|
223 |
|
224 | <script>
|
225 | export default {
|
226 | methods: {
|
227 | onOpen() {
|
228 | this.$refs.tooltip.$emit('open')
|
229 | },
|
230 | onClose() {
|
231 | this.$refs.tooltip.$emit('close')
|
232 | }
|
233 | }
|
234 | }
|
235 | </script>
|
236 |
|
237 | <!-- b-tooltip-show-ref-event.vue -->
|
238 | ```
|
239 |
|
240 | You can also use `$root` events to trigger the showing and hiding of tooltip(s). See the **Hiding
|
241 | and showing tooltips via \$root events** section below for details.
|
242 |
|
243 | ### Programmatically disabling tooltip
|
244 |
|
245 | You can disable tooltip via the syncable Boolean prop `disabled` (default is `false`) Setting it to
|
246 | `true` will disable the tooltip. If the tooltip is currently visible when disabled is set to
|
247 | `false`, the tooltip will remain visible until it is enabled or programmatically closed. If the
|
248 | tooltip is disabled/enabled via \$root events (see below), your `disabled` value will be updated as
|
249 | long as you have provided the `.sync` prop modifier.
|
250 |
|
251 | ```html
|
252 | <template>
|
253 | <div class="d-flex flex-column text-md-center">
|
254 | <div class="p-2">
|
255 | <b-button id="tooltip-button-disable" variant="primary">I have a tooltip</b-button>
|
256 | </div>
|
257 |
|
258 | <div class="p-2">
|
259 | <b-button @click="disabled = !disabled">
|
260 | {{ disabled ? 'Enable' : 'Disable' }} Tooltip by prop
|
261 | </b-button>
|
262 | <b-button @click="disableByRef">
|
263 | {{ disabled ? 'Enable' : 'Disable' }} Tooltip by $ref event
|
264 | </b-button>
|
265 |
|
266 | <b-tooltip :disabled.sync="disabled" ref="tooltip" target="tooltip-button-disable">
|
267 | Hello <strong>World!</strong>
|
268 | </b-tooltip>
|
269 | </div>
|
270 | </div>
|
271 | </template>
|
272 |
|
273 | <script>
|
274 | export default {
|
275 | data() {
|
276 | return {
|
277 | disabled: false
|
278 | }
|
279 | },
|
280 | methods: {
|
281 | disableByRef() {
|
282 | if (this.disabled) {
|
283 | this.$refs.tooltip.$emit('enable')
|
284 | } else {
|
285 | this.$refs.tooltip.$emit('disable')
|
286 | }
|
287 | }
|
288 | }
|
289 | }
|
290 | </script>
|
291 |
|
292 | <!-- b-tooltip-disable.vue -->
|
293 | ```
|
294 |
|
295 | **Note:** _In the above example, since we are using the default tooltip triggers of `focus hover`,
|
296 | the tooltip will close before it is disabled due to loosing focus (and hover) to the toggle button._
|
297 |
|
298 | You can also emit `$root` events to trigger disabling and enabling of tooltip(s). See the
|
299 | **Disabling and enabling tooltips via \$root events** section below for details.
|
300 |
|
301 | You can also emit `$root` events to trigger disabling and enabling of popover(s). See the
|
302 | **Disabling and enabling tooltips via \$root events** section below for details.
|
303 |
|
304 | ## `v-b-tooltip` directive usage
|
305 |
|
306 | The `v-b-tooltip` directive makes adding tooltips even easier, without additional placeholder
|
307 | markup:
|
308 |
|
309 | ```html
|
310 | <b-container fluid>
|
311 | <b-row>
|
312 | <b-col md="6" class="py-4">
|
313 | <b-button v-b-tooltip title="Online!" variant="outline-success">Live chat</b-button>
|
314 | </b-col>
|
315 |
|
316 | <b-col md="6" class="py-4">
|
317 | <b-button
|
318 | v-b-tooltip.html
|
319 | title="Hello <strong>World!</strong>"
|
320 | variant="outline-success"
|
321 | >
|
322 | Html chat
|
323 | </b-button>
|
324 | </b-col>
|
325 | </b-row>
|
326 | </b-container>
|
327 |
|
328 | <!-- b-tooltip-directive.vue -->
|
329 | ```
|
330 |
|
331 | Refer to the [`v-b-tooltip` documentation](/docs/directives/tooltip) for more information and
|
332 | features of the directive format.
|
333 |
|
334 | ## 'Global' \$root instance events
|
335 |
|
336 | Using `$root` instance it is possible to emit and listen events somewhere out of a component, where
|
337 | `<b-collapse>` is used. In short, `$root` behaves like a global event emitters and listener. Details
|
338 | about `$root` instance can be found in
|
339 | [the official Vue docs](https://vuejs.org/v2/guide/components-edge-cases.html#Accessing-the-Root-Instance).
|
340 |
|
341 | ### Hiding and showing tooltips via \$root events
|
342 |
|
343 | You can close (hide) **all open tooltips** by emitting the `bv::hide::tooltip` event on \$root:
|
344 |
|
345 | ```js
|
346 | this.$root.$emit('bv::hide::tooltip')
|
347 | ```
|
348 |
|
349 | To close a **specific tooltip**, pass the trigger element's `id` as the argument:
|
350 |
|
351 | ```js
|
352 | this.$root.$emit('bv::show::tooltip', 'my-trigger-button-id')
|
353 | ```
|
354 |
|
355 | To open a **specific tooltip**, pass the trigger element's `id` as the argument when emitting the
|
356 | `bv::show::tooltip` \$root event:
|
357 |
|
358 | ```js
|
359 | this.$root.$emit('bv::show::tooltip', 'my-trigger-button-id')
|
360 | ```
|
361 |
|
362 | To open all tooltips simultaneously, omit the `id` argument when emitting the `bv::show::tooltip`
|
363 | event.
|
364 |
|
365 | These events work for both the component **and** directive versions of tooltip.
|
366 |
|
367 | **Note:** _the **trigger element** must exist in the DOM and be in a visible state in order for the
|
368 | tooltip to show._
|
369 |
|
370 | ### Disabling and enabling tooltips via \$root events
|
371 |
|
372 | You can disable **all open tooltips** by emitting the `bv::disable::tooltip` event on \$root:
|
373 |
|
374 | ```js
|
375 | this.$root.$emit('bv::disable::tooltip')
|
376 | ```
|
377 |
|
378 | To disable a **specific tooltip**, pass the trigger element's `id` as the argument:
|
379 |
|
380 | ```js
|
381 | this.$root.$emit('bv::disable::tooltip', 'my-trigger-button-id')
|
382 | ```
|
383 |
|
384 | To enable a **specific tooltip**, pass the trigger element's `id` as the argument when emitting the
|
385 | `bv::enable::tooltip` \$root event:
|
386 |
|
387 | ```js
|
388 | this.$root.$emit('bv::enable::tooltip', 'my-trigger-button-id')
|
389 | ```
|
390 |
|
391 | To enable all tooltips simultaneously, omit the `id` argument when emitting the
|
392 | `bv::enable::tooltip` event.
|
393 |
|
394 | These events work for both the component **and** directive versions of tooltip.
|
395 |
|
396 | **Note:** _The **trigger element** must exist in the DOM in order for the tooltip to be enabled or
|
397 | disabled._
|
398 |
|
399 | ### Listening to tooltip changes via \$root events
|
400 |
|
401 | To listen to any tooltip opening, use:
|
402 |
|
403 | ```js
|
404 | export default {
|
405 | mounted() {
|
406 | this.$root.$on('bv::tooltip::show', bvEvent => {
|
407 | console.log('bvEvent:', bvEvent)
|
408 | })
|
409 | }
|
410 | }
|
411 | ```
|
412 |
|
413 | Refer to the [Events](/docs/components/tooltip#component-reference) section of documentation for the
|
414 | full list of events.
|
415 |
|
416 |
|