README.md
Tooltip
Easily add tooltips to elements or components via the
<b-tooltip>
component or <code>v-b-tooltip</code> directive (preferred method).
<div class="text-center my-3">
<b-button v-b-tooltip.hover title="Tooltip directive content">
Hover Me
</b-button>
<b-button id="tooltip-target-1">
Hover Me
</b-button>
<b-tooltip target="tooltip-target-1" triggers="hover">
I am tooltip <b>component</b> content!
</b-tooltip>
</div>
<!-- b-tooltip.vue -->
Overview
Things to know when using tooltip component:
- Tooltips rely on the 3rd party library Popper.js for positioning.
- Tooltips require BootstrapVue's custom SCSS/CSS in order to function correctly, and for variants.
- Triggering tooltips on hidden elements will not work.
- Specify
container
asnull
(default, appends to<body>
) to avoid rendering problems in more complex components (like input groups, button groups, etc.). You can use container to optionally specify a different element to append the rendered tooltip to. - Tooltips for
disabled
elements must be triggered on a wrapper element. - When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use
white-space: nowrap; on your
<a>
s,<b-link>
s and<router-link>
s to avoid this behavior.
Target
The target is the trigger element (or component) that will trigger the tooltip. The target is
specified via the target
prop, and can be any of the following:
- A string identifying the ID of the trigger element (or ID of the root element of a component)
- A reference (ref) to an
HTMLElement
or anSVGElement
(e.g.this.$refs.refName
) - A reference (ref) to a component that has either an
HTMLElement
orSVGElement
as its root element (e.g.this.$refs.refName
) - A function (callback) that returns a reference to an
HTMLElement
orSVGElement
For more information on references, see the official Vue documentation.
Note:
The target element must exist in the document before <b-tooltip>
is mounted. If the target
element is not found during mount, the tooltip will never open. Always place your <b-tooltip>
component lower in the DOM than your target element. This rule also applies if a callback function
is used as target element, since that callback is called only once on mount.
HTMLElement
refers to standard HTML elements such as <div>
, <button>
, etc, while SVGElement
refers to <svg>
or supported child elements of SVGs.
Positioning
Twelve options are available for positioning: top
, topleft
, topright
, right
, righttop
,
rightbottom
, bottom
, bottomleft
, bottomright
, left
, lefttop
, and leftbottom
aligned.
The default position is top
. Positioning is relative to the trigger element.
Tooltip on the top Tooltip on the topleft Tooltip on the topright Tooltip on the right Tooltip on the righttop Tooltip on the rightbottom Tooltip on the bottom Tooltip on the bottomleft Tooltip on the bottomright Tooltip on the left Tooltip on the lefttop Tooltip on the leftbottom
Refer to the Tooltip directive documentation for live examples of positioning.
Triggers
Tooltips can be triggered (opened/closed) via any combination of click
, hover
and focus
. The
default trigger is hover focus
. Or a trigger of manual
can be specified, where the popover can
only be opened or closed programmatically.
If a tooltip has more than one trigger, then all triggers must be cleared before the tooltip will
close. I.e. if a tooltip has the trigger focus click
, and it was opened by focus
, and the user
then clicks the trigger element, they must click it again and move focus to close the tooltip.
Caveats with focus
trigger on <button>
elements
For proper cross-browser and cross-platform behavior when using only the focus
trigger, you must
use an element that renders the <a>
tag, not the <button>
tag, and you also must include a
tabindex="0"
attribute.
The following will generate an <a>
that looks like a button:
<b-button
href="#"
tabindex="0"
v-b-tooltip.focus
title="Tooltip title"
>
Link button with tooltip directive
</b-button>
<b-button id="link-button" href="#" tabindex="0">
Link button with tooltip component
</b-button>
<b-tooltip target="link-button" title="Tooltip title" triggers="focus">
Tooltip title
</b-tooltip>
Making tooltips work for keyboard and assistive technology users
You should only add tooltips to HTML elements that are traditionally keyboard-focusable and
interactive (such as links, buttons, or form controls). Although arbitrary HTML elements (such as
<span>
s) can be made focusable by adding the tabindex="0"
attribute, this will add potentially
annoying and confusing tab stops on non-interactive elements for keyboard users. In addition, most
assistive technologies currently do not announce the tooltip in this situation.
Additionally, do not rely solely on hover
as the trigger for your tooltip, as this will make your
tooltips impossible to trigger for keyboard-only users.
Disabled elements
Elements with the disabled
attribute aren’t interactive, meaning users cannot focus, hover, or
click them to trigger a tooltip (or popover). As a workaround, you’ll want to trigger the tooltip
from a wrapper <div>
or <span>
, ideally made keyboard-focusable using tabindex="0"
, and
override the pointer-events
on the disabled element.
<div>
<span id="disabled-wrapper" class="d-inline-block" tabindex="0">
<b-button variant="primary" style="pointer-events: none;" disabled>Disabled button</b-button>
</span>
<b-tooltip target="disabled-wrapper">Disabled tooltip</b-tooltip>
</div>
<!-- disabled-trigger-element.vue -->
<b-tooltip>
component usage
<b-container fluid>
<b-row>
<b-col md="4" class="py-4">
<b-button id="button-1" variant="outline-success">Live chat</b-button>
</b-col>
<b-col md="4" class="py-4">
<b-button id="button-2" variant="outline-success">Html chat</b-button>
</b-col>
<b-col md="4" class="py-4">
<b-button ref="button-3" variant="outline-success">Alternative chat</b-button>
</b-col>
</b-row>
<!-- Tooltip title specified via prop title -->
<b-tooltip target="button-1" title="Online!"></b-tooltip>
<!-- HTML title specified via default slot -->
<b-tooltip target="button-2" placement="bottom">
Hello <strong>World!</strong>
</b-tooltip>
<!-- Tooltip for an element identified by ref -->
<b-tooltip :target="() => $refs['button-3']" title="Alternative!"></b-tooltip>
</b-container>
<!-- b-tooltip-component.vue -->
Component options
Prop | Default | Description | Supported values |
---|---|---|---|
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 |
title |
null |
Tooltip content (text only, no HTML). if HTML is required, place it in the default slot | Plain text |
placement |
'top' |
Tooltip position, relative to the trigger element | top , bottom , left , right , auto , topleft , topright , bottomleft , bottomright , lefttop , leftbottom , righttop , rightbottom |
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 |
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 . |
no-fade |
false |
Disable fade animation when set to true |
true or false |
delay |
50 |
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. |
offset |
0 |
Shift the center of the tooltip by specified number of pixels | Any negative or positive integer |
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. |
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. |
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 |
noninteractive |
false |
Whether the tooltip should not be user-interactive | true or false |
variant |
null |
Contextual color variant for the tooltip | Any contextual theme color variant name |
custom-class |
null |
A custom classname to apply to the tooltip outer wrapper element | A string |
id |
null |
An ID to use on the tooltip root element. If none is provided, one will automatically be generated. If you do provide an ID, it must be guaranteed to be unique on the rendered page | A valid unique element ID string |
Noninteractive tooltips
BootstrapVue's tooltips are user-interactive by default for accessibility reasons. To restore
Bootstraps default behavior apply the noninteractive
prop:
<div class="text-center">
<div>
<b-button id="tooltip-button-interactive">My tooltip is interactive</b-button>
<b-tooltip target="tooltip-button-interactive">I will stay open when hovered</b-tooltip>
</div>
<div class="mt-3">
<b-button id="tooltip-button-not-interactive">Mine is not...</b-button>
<b-tooltip target="tooltip-button-not-interactive" noninteractive>Catch me if you can!</b-tooltip>
</div>
</div>
<!-- b-tooltip-interactive.vue -->
Variants and custom class
BootstrapVue's tooltips support contextual color variants via our custom CSS, via the variant
prop:
<div class="text-center">
<b-button id="tooltip-button-variant">Button</b-button>
<b-tooltip target="tooltip-button-variant" variant="danger">Danger variant tooltip</b-tooltip>
</div>
<!-- b-tooltip-variant.vue -->
Bootstrap default theme variants are: danger
, warning
, success
, primary
, secondary
,
info
, light
, and dark
. You can change or add additional variants via Bootstrap
SCSS variables
A custom class can be applied to the tooltip outer wrapper <div>
by using the custom-class
prop:
<div class="text-center">
<b-button id="my-button">Button</b-button>
<b-tooltip target="my-button" custom-class="my-tooltip-class">Tooltip Title</b-tooltip>
</div>
variant
and custom-class
are reactive and can be changed while the tooltip is open.
Refer to the tooltip directive docs on applying variants and custom class to the directive version.
Programmatically show and hide tooltip
You can manually control the visibility of a tooltip via the syncable Boolean show
prop. Setting
it to true
will show the tooltip, while setting it to false
will hide the tooltip.
<template>
<div class="text-center">
<div>
<b-button id="tooltip-button-1" variant="primary">I have a tooltip</b-button>
</div>
<div class="mt-3">
<b-button @click="show = !show">Toggle Tooltip</b-button>
</div>
<b-tooltip :show.sync="show" target="tooltip-button-1" placement="top">
Hello <strong>World!</strong>
</b-tooltip>
</div>
</template>
<script>
export default {
data: {
show: true
}
}
</script>
<!-- b-tooltip-show-sync.vue -->
To make the tooltip shown on initial render, simply add the show
prop on <b-tooltip>
:
<div class="text-center">
<b-button id="tooltip-button-2" variant="primary">Button</b-button>
<b-tooltip show target="tooltip-button-2">I start open</b-tooltip>
</div>
<!-- b-tooltip-show-open.vue -->
Programmatic control can also be affected by submitting 'open'
and 'close'
events to the tooltip
by reference.
<template>
<div class="d-flex flex-column text-md-center">
<div class="p-2">
<b-button id="tooltip-button-show-event" variant="primary">I have a tooltip</b-button>
</div>
<div class="p-2">
<b-button class="px-1" @click="onOpen">Open</b-button>
<b-button class="px-1" @click="onClose">Close</b-button>
</div>
<b-tooltip ref="tooltip" target="tooltip-button-show-event">
Hello <strong>World!</strong>
</b-tooltip>
</div>
</template>
<script>
export default {
methods: {
onOpen() {
this.$refs.tooltip.$emit('open')
},
onClose() {
this.$refs.tooltip.$emit('close')
}
}
}
</script>
<!-- b-tooltip-show-ref-event.vue -->
You can also use $root
events to trigger the showing and hiding of tooltip(s). See the Hiding
and showing tooltips via \$root events section below for details.
Programmatically disabling tooltip
You can disable tooltip via the syncable Boolean prop disabled
(default is false
) Setting it to
true
will disable the tooltip. If the tooltip is currently visible when disabled is set to
false
, the tooltip will remain visible until it is enabled or programmatically closed. If the
tooltip is disabled/enabled via \$root events (see below), your disabled
value will be updated as
long as you have provided the .sync
prop modifier.
<template>
<div class="d-flex flex-column text-md-center">
<div class="p-2">
<b-button id="tooltip-button-disable" variant="primary">I have a tooltip</b-button>
</div>
<div class="p-2">
<b-button @click="disabled = !disabled">
{{ disabled ? 'Enable' : 'Disable' }} Tooltip by prop
</b-button>
<b-button @click="disableByRef">
{{ disabled ? 'Enable' : 'Disable' }} Tooltip by $ref event
</b-button>
<b-tooltip :disabled.sync="disabled" ref="tooltip" target="tooltip-button-disable">
Hello <strong>World!</strong>
</b-tooltip>
</div>
</div>
</template>
<script>
export default {
data() {
return {
disabled: false
}
},
methods: {
disableByRef() {
if (this.disabled) {
this.$refs.tooltip.$emit('enable')
} else {
this.$refs.tooltip.$emit('disable')
}
}
}
}
</script>
<!-- b-tooltip-disable.vue -->
Note: In the above example, since we are using the default tooltip triggers of focus hover
,
the tooltip will close before it is disabled due to losing focus (and hover) to the toggle button.
You can also emit $root
events to trigger disabling and enabling of tooltip(s). See the
Disabling and enabling tooltips via \$root events section below for details.
You can also emit $root
events to trigger disabling and enabling of popover(s). See the
Disabling and enabling tooltips via \$root events section below for details.
v-b-tooltip
directive usage
The v-b-tooltip
directive makes adding tooltips even easier, without additional placeholder
markup:
<b-container fluid>
<b-row>
<b-col md="6" class="py-4">
<b-button v-b-tooltip title="Online!" variant="outline-success">Live chat</b-button>
</b-col>
<b-col md="6" class="py-4">
<b-button
v-b-tooltip.html
title="Hello <strong>World!</strong>"
variant="outline-success"
>
Html chat
</b-button>
</b-col>
</b-row>
</b-container>
<!-- b-tooltip-directive.vue -->
Refer to the <code>v-b-tooltip</code> documentation for more information and features of the directive format.
'Global' \$root instance events
Using $root
instance it is possible to emit and listen events somewhere out of a component, where
<b-collapse>
is used. In short, $root
behaves like a global event emitters and listener. Details
about $root
instance can be found in
the official Vue docs.
Hiding and showing tooltips via \$root events
You can close (hide) all open tooltips by emitting the bv::hide::tooltip
event on \$root:
this.$root.$emit('bv::hide::tooltip')
To close a specific tooltip, pass the trigger element's id
, or the id
of the tooltip (if one
was provided via the id
prop), as the argument:
this.$root.$emit('bv::hide::tooltip', 'my-trigger-button-id')
To open a specific tooltip, pass the trigger element's id
, or the id
of the tooltip (if one
was provided via the id
prop), as the argument when emitting the bv::show::tooltip
\$root event:
this.$root.$emit('bv::show::tooltip', 'my-trigger-button-id')
To open all tooltips simultaneously, omit the id
argument when emitting the bv::show::tooltip
event.
These events work for both the component and directive versions of tooltip.
Note: the trigger element must exist in the DOM and be in a visible state in order for the tooltip to show.
Disabling and enabling tooltips via \$root events
You can disable all open tooltips by emitting the bv::disable::tooltip
event on \$root:
this.$root.$emit('bv::disable::tooltip')
To disable a specific tooltip, pass the trigger element's id
, or the id
of the tooltip (if
one was provided via the id
prop), as the argument:
this.$root.$emit('bv::disable::tooltip', 'my-trigger-button-id')
To enable a specific tooltip, pass the trigger element's id
, or the id
of the tooltip (if
one was provided via the id
prop), as the argument when emitting the bv::enable::tooltip
\$root
event:
this.$root.$emit('bv::enable::tooltip', 'my-trigger-button-id')
To enable all tooltips simultaneously, omit the id
argument when emitting the
bv::enable::tooltip
event.
These events work for both the component and directive versions of tooltip.
Note: The trigger element must exist in the DOM in order for the tooltip to be enabled or disabled.
Listening to tooltip changes via \$root events
To listen to any tooltip opening, use:
export default {
mounted() {
this.$root.$on('bv::tooltip::show', bvEvent => {
console.log('bvEvent:', bvEvent)
})
}
}
Refer to the Events section of documentation for the full list of events.
Accessibility
The trigger element, when the tooltip is showing, will have the attribute aria-describedby
set
with the auto generated ID of the tooltip.
Note: The animation effect of this component is dependent on the prefers-reduced-motion
media
query. See the
reduced motion section of our accessibility documentation for
additional details.
<!-- Component reference added automatically from component package.json -->