vue-tippy

VueTippy is a Vue 3 wrapper for the Tippy.js library, providing tooltips, popovers, dropdowns, and menus. It is powered by Popper and offers several key features:

• Optimized positioning engine: Handles flipping and overflow prevention.
• Accessibility: WAI-ARIA compliant by default.
• Customization: Themeable via custom CSS, including extra themes and animations.
• TypeScript Support: Built-in support for TypeScript.
• Multiple Usage Patterns: Can be used as a Vue Directive (v-tippy), a Vue Component (<tippy />), or via the Composition API (useTippy()).

To create custom themes, you need to understand the nested structure of a Tippy element:

• [data-tippy-root]: The outermost node used by Popper for positioning. Do not apply styles here.
• .tippy-box: The actual container box.
• .tippy-content: The node containing your content.

Optional elements:

• .tippy-backdrop: Appears if animateFill: true is set.
• .tippy-arrow: The arrow element (appears if arrow: true).

<div data-tippy-root>
  <div class="tippy-box" data-placement="top">
    <div class="tippy-backdrop"></div>
    <div class="tippy-arrow"></div>
    <div class="tippy-content">
      My content
    </div>
  </div>
</div>

You can use the v-tippy directive to attach tooltips to any element. You can pass a configuration object to define multiple properties, or pass a simple string for just the tooltip content.

If you haven't installed the plugin globally, you must import directive from vue-tippy and register it in your component's directives option.

<template>
  <!-- Using an object for configuration -->
  <button v-tippy="{ content: 'Hi!' }">Tippy!</button>
  
  <!-- Using a simple string for content -->
  <button v-tippy="'Hello!'">Tippy!</button>
</template>

<script>
  import { directive } from 'vue-tippy'

  export default {
    directives: {
      tippy: directive,
    },
  }
</script>

To create a production-ready static build in the dist/ directory for static hosting, run the generate command. To preview the resulting static application, use the start command.

yarn generate
# To preview the generated app:
yarn start

You can configure Tippy using three different methods in Vue:

1. Directive: Pass a props object to v-tippy.
2. Component: Pass props directly to the <tippy> component.
3. Composition API: Use the useTippy(target, props) hook.

All configuration is handled via a props object.

<!-- Tippy Directive -->
<button v-tippy="props">Hello</button>

<!-- Tippy Component -->
<tippy prop1 prop2 ...>
  <button>World!</button>
</tippy>

// Composition api
useTippy(target, props)

CSS arrows are styled by targeting the .tippy-arrow::before pseudo-element. Because the arrow direction changes based on placement, you must target the placement using the data-placement attribute.

Implementation:

/* Top placement */
.tippy-box[data-theme~='tomato'][data-placement^='top'] > .tippy-arrow::before {
  border-top-color: tomato;
}

/* Bottom placement */
.tippy-box[data-theme~='tomato'][data-placement^='bottom'] > .tippy-arrow::before {
  border-bottom-color: tomato;
}

/* Left placement */
.tippy-box[data-theme~='tomato'][data-placement^='left'] > .tippy-arrow::before {
  border-left-color: tomato;
}

/* Right placement */
.tippy-box[data-theme~='tomato'][data-placement^='right'] > .tippy-arrow::before {
  border-right-color: tomato;
}

There are two ways to change the size of a Tippy arrow:

Option 1: transform: scale()

The simplest method. This works for most standard themes.

.tippy-box[data-theme~='tomato'] > .tippy-arrow::before {
  transform: scale(1.5);
}

Option 2: Pixel increase

If your theme uses a border (like the light-border theme), transform: scale() will distort the border width. In this case, you must manually adjust the arrow size using pixel values directly in your CSS.

The <tippy> component wraps a trigger element and displays content. You can provide content in two ways:

1. Via the content prop.
2. Via the #content slot.

If you haven't installed the plugin globally, import Tippy from vue-tippy and register it in your component's components option.

<template>
  <!-- Using the content prop -->
  <tippy content="Hi!">
    <button>Tippy!</button>
  </tippy>

  <!-- Using the #content slot -->
  <tippy>
    <button>Tippy!</button>

    <template #content>
      Hi!
    </template>
  </tippy>
</template>

<script>
  import { Tippy } from 'vue-tippy'

  export default {
    components: {
      Tippy,
    },
  }
</script>

For complex animations that require @keyframes or external libraries like animate.css, use the onMount and onHidden lifecycle hooks to manually add or remove CSS classes from the tippy box element.

The tippy box can be accessed via instance.popper.firstElementChild.

useTippy(target, {
  onMount(instance) {
    const box = instance.popper.firstElementChild
    requestAnimationFrame(() => {
      box.classList.add('animated')
      box.classList.add('wobble')
    })
  },
  onHidden(instance) {
    const box = instance.popper.firstElementChild
    box.classList.remove('animated')
    box.classList.remove('wobble')
  },
})

To achieve a Material-style filling effect, you must import both the backdrop CSS and the shift-away animation CSS, then enable the animateFill prop.

import 'tippy.js/dist/backdrop.css'
import 'tippy.js/animations/shift-away.css'

useTippy(target, {
  animateFill: true,
})

You can define custom animations by targeting the .tippy-box element with specific data attributes in your CSS:

1. Use the [data-animation] attribute to specify your custom animation name.
2. Target the visibility state using [data-state="hidden"] or [data-state="visible"].
3. (Optional) Target specific placements using attribute selectors like [data-placement^="top"].

After defining the CSS, pass the custom name to the animation prop.

/* CSS Definition */
.tippy-box[data-animation='rotate'][data-state='hidden'] {
  opacity: 0;
  transform: rotate(90deg);
}

/* Usage */
useTippy(target, {
  animation: 'rotate',
})