bootstrap-vue

Version:

With more than 85 components, over 45 available plugins, several directives, and 1000+ icons, BootstrapVue provides one of the most comprehensive implementations of the Bootstrap v4 component and grid system available for Vue.js v2.6, complete with extens

bootstrap-vue.org

bootstrap-vue/bootstrap-vue

560 lines (442 loc) • 25.6 kB

Markdown

# Tooltip > Easily add tooltips to elements or components via the `<b-tooltip>` component or > [`v-b-tooltip`](/docs/directives/tooltip) directive (preferred method). ```html <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>  ``` ## Overview Things to know when using tooltip component: - Tooltips rely on the 3rd party library [Popper.js](https://popper.js.org/) 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` as `null` (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 an `SVGElement` (e.g. `this.$refs.refName`) - A reference (ref) to a component that has either an `HTMLElement` or `SVGElement` as its root element (e.g. `this.$refs.refName`) - A function (callback) that returns a reference to an `HTMLElement` or `SVGElement` For more information on references, see the official [Vue documentation](https://vuejs.org/v2/api/#vm-refs). **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. <div class="bd-example bd-example-tooltip-static"> <div class="tooltip b-tooltip bs-tooltip-top bs-tooltip-top-docs" role="tooltip"> <div class="arrow" style="left: calc(50% - 6px)"></div> <div class="tooltip-inner">Tooltip on the top</div> </div> <div class="tooltip b-tooltip bs-tooltip-top bs-tooltip-top-docs" role="tooltip"> <div class="arrow" style="right: 0px"></div> <div class="tooltip-inner">Tooltip on the topleft</div> </div> <div class="tooltip b-tooltip bs-tooltip-top bs-tooltip-top-docs" role="tooltip"> <div class="arrow" style="left: 0px"></div> <div class="tooltip-inner">Tooltip on the topright</div> </div> <div class="tooltip b-tooltip bs-tooltip-right bs-tooltip-right-docs" role="tooltip"> <div class="arrow" style="top: 5px"></div> <div class="tooltip-inner">Tooltip on the right</div> </div> <div class="tooltip b-tooltip bs-tooltip-right bs-tooltip-right-docs" role="tooltip"> <div class="arrow" style="bottom: 0px"></div> <div class="tooltip-inner">Tooltip on the righttop</div> </div> <div class="tooltip b-tooltip bs-tooltip-right bs-tooltip-right-docs" role="tooltip"> <div class="arrow" style="top: 0px"></div> <div class="tooltip-inner">Tooltip on the rightbottom</div> </div> <div class="tooltip b-tooltip bs-tooltip-bottom bs-tooltip-bottom-docs" role="tooltip"> <div class="arrow" style="left: calc(50% - 6px)"></div> <div class="tooltip-inner">Tooltip on the bottom</div> </div> <div class="tooltip b-tooltip bs-tooltip-bottom bs-tooltip-bottom-docs" role="tooltip"> <div class="arrow" style="right: 0px"></div> <div class="tooltip-inner">Tooltip on the bottomleft</div> </div> <div class="tooltip b-tooltip bs-tooltip-bottom bs-tooltip-bottom-docs" role="tooltip"> <div class="arrow" style="left: 0px"></div> <div class="tooltip-inner">Tooltip on the bottomright</div> </div> <div class="tooltip b-tooltip bs-tooltip-left bs-tooltip-left-docs" role="tooltip"> <div class="arrow" style="top: 5px"></div> <div class="tooltip-inner">Tooltip on the left</div> </div> <div class="tooltip b-tooltip bs-tooltip-left bs-tooltip-left-docs" role="tooltip"> <div class="arrow" style="bottom: 0px"></div> <div class="tooltip-inner">Tooltip on the lefttop</div> </div> <div class="tooltip b-tooltip bs-tooltip-left bs-tooltip-left-docs" role="tooltip"> <div class="arrow" style="top: 0px"></div> <div class="tooltip-inner">Tooltip on the leftbottom</div> </div> </div> Refer to the [Tooltip directive](/docs/directives/tooltip/#positioning) 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](#programmatically-disabling-tooltip). 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: ```html <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. ```html <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>  ``` ## `<b-tooltip>` component usage ```html <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>  <b-tooltip target="button-1" title="Online!"></b-tooltip>  <b-tooltip target="button-2" placement="bottom"> Hello <strong>World!</strong> </b-tooltip>  <b-tooltip :target="() => $refs['button-3']" title="Alternative!"></b-tooltip> </b-container>  ``` ### 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: ```html <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>  ``` ### Variants and custom class BootstrapVue's tooltips support contextual color variants via our custom CSS, via the `variant` prop: ```html <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>  ``` 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](/docs/reference/theming) A custom class can be applied to the tooltip outer wrapper `<div>` by using the `custom-class` prop: ```html <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/directives/tooltip) 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. ```html <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>  ``` To make the tooltip shown on initial render, simply add the `show` prop on `<b-tooltip>`: ```html <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>  ``` Programmatic control can also be affected by submitting `'open'` and `'close'` events to the tooltip by reference. ```html <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>  ``` 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. ```html <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>  ``` **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: ```html <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>  ``` Refer to the [`v-b-tooltip` documentation](/docs/directives/tooltip) 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](https://vuejs.org/v2/guide/components-edge-cases.html#Accessing-the-Root-Instance). ### Hiding and showing tooltips via \$root events You can close (hide) **all open tooltips** by emitting the `bv::hide::tooltip` event on \$root: ```js 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: ```js 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: ```js 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: ```js 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: ```js 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: ```js 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: ```js export default { mounted() { this.$root.$on('bv::tooltip::show', bvEvent => { console.log('bvEvent:', bvEvent) }) } } ``` Refer to the [Events](/docs/components/tooltip#component-reference) 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](/docs/reference/accessibility) for additional details.