Skip to content
On this page

Tooltip

Example

The first element appear in <tooltip> node will be the trigger element. You can also use target to reference it from outside the component.

TIP

Tooltips with zero-length texts are never displayed.

Hover over the button below to toggle tooltips:

vue
<template>
  <Btn id="btn" type="primary">Hover me!</Btn>
  <Tooltip text="Static tooltip content goes here" target="#btn" />
</template>

<script setup>
import { Btn, Tooltip } from 'uiv';
</script>

Trigger target

Order to decide the tooltip trigger:

  1. Use target if exist.
  2. Use element in default slot with data-role="trigger" attribute if exist.
  3. Use the first element present in default slot.

A target can be:

  • Selector that can be recognized by querySelect.
  • Reference to Element.
  • Reference to Component.

Directive

You can also simply use tooltips via v-tooltip directive:

vue
<template>
  <Btn v-tooltip="'Static tooltip content goes here'" type="primary">
    Hover me!
  </Btn>
</template>

<script setup>
import { Btn, tooltip as vTooltip } from 'uiv';
</script>

Placements

Supported placements:

  • top (Default)
  • right
  • bottom
  • left
vue
<template>
  <Btn v-tooltip.left="'Tooltip content on left'" type="primary">Left</Btn>
  <Btn v-tooltip.top="'Tooltip content on top'" type="primary">Top</Btn>
  <Btn v-tooltip.bottom="'Tooltip content on bottom'" type="primary">
    Bottom
  </Btn>
  <Btn v-tooltip.right="'Tooltip content on right'" type="primary">Right</Btn>
</template>

<script setup>
import { Btn, tooltip as vTooltip } from 'uiv';
</script>

Auto placement

Tooltips will try to find the best placement for displaying while auto-placement is set to true (by default) base on the default placement setting. Useful while there does not have enough space to show the entire tooltip content.

auto-placement try order: right -> bottom -> left -> top, and use the set one if none of these matched.

Viewport

Keeps the tooltip within the bounds of this element.

vue
<template>
  <div id="tooltip-viewport">
    <Btn
      v-tooltip="{
        text: 'Tooltip content auto',
        viewport: '#tooltip-viewport',
      }"
      type="primary"
    >
      Auto
    </Btn>
    <Btn
      v-tooltip.left="{
        text: 'Tooltip content on left',
        viewport: '#tooltip-viewport',
      }"
      type="primary"
    >
      Left
    </Btn>
    <Btn
      v-tooltip.top="{
        text: 'Tooltip content on top',
        viewport: '#tooltip-viewport',
      }"
      type="primary"
    >
      Top
    </Btn>
    <Btn
      v-tooltip.bottom="{
        text: 'Tooltip content on bottom',
        viewport: '#tooltip-viewport',
      }"
      type="primary"
    >
      Bottom
    </Btn>
    <Btn
      v-tooltip.right="{
        text: 'Tooltip content on right',
        viewport: '#tooltip-viewport',
      }"
      type="primary"
    >
      Right
    </Btn>
    <Btn
      v-tooltip="{
        text: 'Tooltip content auto',
        viewport: '#tooltip-viewport',
      }"
      type="primary"
    >
      Auto
    </Btn>
  </div>
</template>

<script setup>
import { Btn, tooltip as vTooltip } from 'uiv';
</script>

<style scoped>
#tooltip-viewport {
  display: inline-block;
  padding: 20px;
  background-color: #eee;
}
</style>

Triggers

Supported triggers:

  • hover show on mouseenter, hide on mouseleave.
  • focus show on focus, hide on blur.
  • hover-focus (Default) combination of hover and focus trigger.
  • click toggle on trigger click.
  • outside-click same as click, but not close on tooltip click and close on outside click.
vue
<template>
  <Btn v-tooltip="'Static tooltip content'" type="primary">
    Hover-Focus (Default)
  </Btn>
  <Btn v-tooltip.hover="'Static tooltip content'" type="primary">Hover</Btn>
  <Btn v-tooltip.focus="'Static tooltip content'" type="primary">Focus</Btn>
  <Btn v-tooltip.click="'Static tooltip content'" type="primary">Click</Btn>
  <Btn v-tooltip.outside-click="'Static tooltip content'" type="primary">
    Outside-Click
  </Btn>
</template>

<script setup>
import { Btn, tooltip as vTooltip } from 'uiv';
</script>

Manual trigger

Set trigger prop to manual to disable all the event listeners, and controls tooltips show / hide only by v-model change.

vue
<template>
  <Tooltip
    v-model="show"
    text="Static tooltip content goes here"
    trigger="manual"
  >
    <btn>You Can't Trigger Tooltip Here...</btn>
  </Tooltip>
  <hr />
  <Btn type="primary" @click="show = !show">Toggle Tooltip</Btn>
</template>

<script setup>
import { Btn, Tooltip } from 'uiv';
import { ref } from 'vue';

const show = ref(false);
</script>

API Reference

Tooltip

Props

NameTypeDefaultRequiredDescription
v-modelBooleanShow / hide the tooltip.
targetTooltip trigger, can be a select or reference to Element / Component.
tagStringspanThe HTML tag that render the component.
textStringThe tooltip text.
enableBooleantrueEnable the tooltip.
enterableBooleantrueWhether mouse can enter the tooltip.
placementStringtopThe tooltip placement, support top / bottom / left / right.
auto-placementBooleantrueTry to auto adjust the placement if the set one does not have enough space to show.
triggerStringhover-focusThe tooltip trigger event, support hover / focus / hover-focus / click / outside-click / manual
append-toStringbodyElement selector that the tooltip append to.
position-byStringElement selector that the tooltip position by, see #410.
transitionNumber150The tooltip show / hide transition time in ms.
show-delayNumber0Delay showing the tooltip (ms).
hide-delayNumber0Delay hidding the tooltip (ms).
viewportString or FunctionKeeps the tooltip within the bounds of this element. Example: viewport: '#viewport'. If a function is given, it is called with the triggering element DOM node as its only argument.
custom-classStringApply a custom css class to the tooltip.

Events

NameParamsDescription
showFire after tooltip show.
hideFire after tooltip hide.

Directive

The binding value will be the text content of corresponding tooltip.

Simplest Usage

v-tooltip="'tooltip content'"

Placements Examples

v-tooltip.left="'tooltip content'"
v-tooltip.right="'tooltip content'"

Triggers Examples

v-tooltip.hover="'tooltip content'"
v-tooltip.click="'tooltip content'"

Unenterable

v-tooltip.unenterable="'tooltip content'"

Custom append-to

v-tooltip:arg="'tooltip content'"

arg is the ID (without prefix #) of the element to append to, leave it empty to use default value body.

Combination

v-tooltip.left.hover="'tooltip content'"
v-tooltip:some-id.right.click="'tooltip content'"

Released under the MIT License.