thecodewarrior/Tippy.vue

Nesting-free Tippy.js components for Vue 3

Tippy.vue

Nesting-free Tippy.js directive/component for Vue 3

Design

• Easy to use: A clumsy tool will wind up chronically underutilized, so Tippy.vue has been designed with a focus on ergonomics.
• Clean to write: Writing Tippy.vue is clean. We don't use wrapper components, everything is in the default slot, and common options are exposed as props.
• Clean HTML: Tippy.vue mounts itself and then disappears from the DOM tree, leaving your layout untouched.

Examples

<!-- As an inline directive -->
<button v-tippy="`Seconds: ${seconds}`">Counter</button>
<button v-tippy="{content: 'Some content', placement: 'right'}">Side</button>

<!-- As a component -->
<button v-tippy>Counter</button>
<tippy>Time: <i>{{seconds}}</i></tippy>

<button v-tippy:name>Props</button>
<tippy target="name" placement="right">Side tooltip</tippy>

<!-- Target the parent (useful for components adding a tooltips to themselves) -->
<button>
  Button
  <tippy target="_parent">Bound to parent</tippy>
</button>

<!-- Only the commonly-used Tippy.js options have props, but
     other niche options can be passed into the 'extra' prop -->
<button v-tippy>Follow me</button>
<tippy :extra="{followCursor: true}">Tip</tippy>

<!-- Using a singleton -->
<tippy-singleton move-transition="transform 0.1s ease-out"/>
<button v-tippy>Item 1</button> <tippy singleton>Tip 1</tippy>
<button v-tippy>Item 2</button> <tippy singleton>Tip 2</tippy>
<button v-tippy>Item 3</button> <tippy singleton>Tip 3</tippy>

More examples and working demos can be found in the documentation.

Custom Props

Tippy.vue doesn't have a vue property for every Tippy.js prop, instead providing extra for additional options. This is by design, since it keeps the API clean and easy to understand. You can however add you own props without any modifications to the base library. This is a fairly advanced feature, but it's available if needed. See the docs for an overview of the API.

Why?

There's already a popular Vue library for using Tippy.js, VueTippy, so you might (rightfully) ask, why make another one?

To put it simply, VueTippy makes a few structural concessions which I disagree with. The most significant is that when using VueTippy, adding a complex (i.e. non-directive) tooltip to an element will wrap it in a <span>, which can easily screw up a complex layout. On top of that, I find their syntax clunky and ugly. Wrapping every tooltipped component in a slot seems unnecessary.

One of my mottos is that a clumsy tool will wind up chronically underutilized, so Tippy.vue has been designed from the start with a strong focus on ergonomics. Adding a tooltip is a simple, drop-in addition, with no structural or styling changes necessary.

<!-- VueTippy -->
<tippy>
  <button>Tippy!</button>
  
  <template #content>
    Hi!
  </template>
</tippy>

<!-- Tippy.vue -->
<button v-tippy>Tippy!</button>
<tippy>Hi!</tippy>

🚀 Installation

📦 Package Manager

# npm
npm i tippy.vue

# Yarn
yarn add tippy.vue

💻 CDN

Tippy.vue doesn't bundle Tippy.js. The most up-to-date Tippy install process is explained in the Tippy docs, but as of the time of writing, these are the necessary scripts:

<!-- Development -->
<script src="https://unpkg.com/@popperjs/core@2/dist/umd/popper.min.js"></script>
<script src="https://unpkg.com/tippy.js@6/dist/tippy-bundle.umd.js"></script>

<script src="https://unpkg.com/tippy.vue@3"></script>

<!-- Production -->
<script src="https://unpkg.com/@popperjs/core@2"></script>
<script src="https://unpkg.com/tippy.js@6"></script>

<script src="https://unpkg.com/tippy.vue@3"></script>

Usage

📦 Package Manager

You can use Tippy.vue as a plugin or access the individual components directly:

// use the plugin
import {TippyPlugin} from 'tippy.vue';

app.use(TippyPlugin);
app.use(TippyPlugin, {
  tippyDefaults: {}, // convenience to set tippy.js default props
});

// or add them individually
import {TippyDirective, Tippy, TippySingleton} from 'tippy.vue';

app.directive('tippy', TippyDirective);
app.component('tippy', Tippy);
app.component('tippy-singleton', TippySingleton);

import tippy from 'tippy.js'
tippy.setDefaultProps({
  // default tippy props
});

/* add styles/themes to your global stylesheet */
@import '~tippy.js/dist/tippy.css';

You can also add them in individual components:

<template>
  <div>
    <div v-tippy>Wow</div>
    <tippy>Cool</tippy>
  </div>
</template>

<script>
import {Tippy, TippyDirective} from 'tippy.vue'

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

💻 CDN

// use the plugin
app.use(TippyVue);
app.use(TippyVue, {
  tippyDefaults: {}, // convenience to set tippy.js default props
});

// or add them individually
app.directive('tippy', TippyVue.TippyDirective);
app.component('tippy', TippyVue.Tippy);
app.component('tippy-singleton', TippyVue.TippySingleton);
tippy.setDefaultProps({
  // default tippy props
});

Code Completion

Tippy.vue includes code completion files for IntelliJ IDEA, Vetur, and Volar. See the docs for details on how to use them.

Contributing

Setting up an environment is very standard. Make sure you're on the latest version of yarn, then run:

yarn install
yarn docs:dev