UNPKG

19.1 kBMarkdownView Raw
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
16Things 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
30The `<b-tooltip>` component inserts a hidden (`display:none`) `<div>` intermediate container element
31at the point in the DOM where the `<b-tooltip>` component is placed. This may affect layout and/or
32styling of components such as `<b-button-group>`, `<b-button-toolbar>`, and `<b-input-group>`. To
33avoid these possible layout issues, place the `<b-tooltip>` component **outside** of these types of
34components.
35
36The target element **must** exist in the document before `<b-tooltip>` is mounted. If the target
37element is not found during mount, the tooltip will never open. Always place your `<b-tooltip>`
38component lower in the DOM than your target element. This rule also applies if a callback is used as
39target 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
42that slot into the tooltip's markup when shown, and returns the content back to the `<b-tooltip>`
43component when hidden. This may cause some issues in rare circumstances, so please test your
44implementation accordingly! The `title` prop does not have this behavior. For simple tooltips, we
45recommend using the `v-b-tooltip` directive and enable the `html` modifier if needed._
46
47## Positioning
48
49Twelve options are available for positioning: `top`, `topleft`, `topright`, `right`, `righttop`,
50`rightbottom`, `bottom`, `bottomleft`, `bottomright`, `left`, `lefttop`, and `leftbottom` aligned.
51The 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
106Tooltips can be triggered (opened/closed) via any combination of `click`, `hover` and `focus`. The
107default trigger is `hover focus`.
108
109If a tooltip has more than one trigger, then all triggers must be cleared before the tooltip will
110close. I.e. if a tooltip has the trigger `focus click`, and it was opened by `focus`, and the user
111then 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
162You can manually control the visibility of a tooltip via the syncable Boolean `show` prop. Setting
163it 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
192To 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
203Programmatic control can also be affected by submitting `'open'` and `'close'` events to the tooltip
204by 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
240You can also use `$root` events to trigger the showing and hiding of tooltip(s). See the **Hiding
241and showing tooltips via \$root events** section below for details.
242
243### Programmatically disabling tooltip
244
245You 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
248tooltip is disabled/enabled via \$root events (see below), your `disabled` value will be updated as
249long 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`,
296the tooltip will close before it is disabled due to loosing focus (and hover) to the toggle button._
297
298You 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
301You 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
306The `v-b-tooltip` directive makes adding tooltips even easier, without additional placeholder
307markup:
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
331Refer to the [`v-b-tooltip` documentation](/docs/directives/tooltip) for more information and
332features of the directive format.
333
334## 'Global' \$root instance events
335
336Using `$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
338about `$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
343You can close (hide) **all open tooltips** by emitting the `bv::hide::tooltip` event on \$root:
344
345```js
346this.$root.$emit('bv::hide::tooltip')
347```
348
349To close a **specific tooltip**, pass the trigger element's `id` as the argument:
350
351```js
352this.$root.$emit('bv::show::tooltip', 'my-trigger-button-id')
353```
354
355To 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
359this.$root.$emit('bv::show::tooltip', 'my-trigger-button-id')
360```
361
362To open all tooltips simultaneously, omit the `id` argument when emitting the `bv::show::tooltip`
363event.
364
365These 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
368tooltip to show._
369
370### Disabling and enabling tooltips via \$root events
371
372You can disable **all open tooltips** by emitting the `bv::disable::tooltip` event on \$root:
373
374```js
375this.$root.$emit('bv::disable::tooltip')
376```
377
378To disable a **specific tooltip**, pass the trigger element's `id` as the argument:
379
380```js
381this.$root.$emit('bv::disable::tooltip', 'my-trigger-button-id')
382```
383
384To 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
388this.$root.$emit('bv::enable::tooltip', 'my-trigger-button-id')
389```
390
391To enable all tooltips simultaneously, omit the `id` argument when emitting the
392`bv::enable::tooltip` event.
393
394These 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
397disabled._
398
399### Listening to tooltip changes via \$root events
400
401To listen to any tooltip opening, use:
402
403```js
404export default {
405 mounted() {
406 this.$root.$on('bv::tooltip::show', bvEvent => {
407 console.log('bvEvent:', bvEvent)
408 })
409 }
410}
411```
412
413Refer to the [Events](/docs/components/tooltip#component-reference) section of documentation for the
414full list of events.
415
416<!-- Component reference added automatically from component package.json -->