- Notifications
You must be signed in to change notification settings - Fork3
Nesting-free Tippy.js components for Vue 3
License
thecodewarrior/Tippy.vue
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Nesting-freeTippy.js directive/component for Vue 3
- Easy to use: A clumsy tool will wind up chronically underutilized, so Tippy.vue has been designed with a focuson 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.
<!-- 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 placement="right">Side tooltip</tippy><!-- Target the parent (useful for components adding a tooltips to themselves) --><button> Button <tippy>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 foundin the documentation.
Tippy.vue doesn't have a vue property for every Tippy.js prop, instead providingextra for additional options. Thisis by design, since it keeps the API clean and easy to understand. You can however add you own props without anymodifications 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.
There's already a popular Vue library for using Tippy.js,VueTippy, so youmight (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 whenusing VueTippy, adding a complex (i.e. non-directive) tooltip to an element will wrap it in a<span>, which can easilyscrew up a complex layout. On top of that, I find their syntax clunky and ugly. Wrapping every tooltipped component in aslot seems unnecessary.
One of my mottos is that a clumsy tool will wind up chronically underutilized, so Tippy.vue has been designed from thestart with a strong focus on ergonomics. Adding a tooltip is a simple, drop-in addition, with no structural or stylingchanges necessary.
<!-- VueTippy --><tippy><button>Tippy!</button><template#content> Hi!</template></tippy><!-- Tippy.vue --><buttonv-tippy>Tippy!</button><tippy>Hi!</tippy>
# npmnpm i tippy.vue# Yarnyarn add tippy.vue
Tippy.vue doesn't bundle Tippy.js. The most up-to-date Tippy install process is explainedin the Tippy docs, but as of the time of writing, theseare the necessary scripts:
<!-- Development --><scriptsrc="https://unpkg.com/@popperjs/core@2/dist/umd/popper.min.js"></script><scriptsrc="https://unpkg.com/tippy.js@6/dist/tippy-bundle.umd.js"></script><scriptsrc="https://unpkg.com/tippy.vue@3"></script>
<!-- Production --><scriptsrc="https://unpkg.com/@popperjs/core@2"></script><scriptsrc="https://unpkg.com/tippy.js@6"></script><scriptsrc="https://unpkg.com/tippy.vue@3"></script>
You can use Tippy.vue as a plugin or access the individual components directly:
// use the pluginimport{TippyPlugin}from'tippy.vue';app.use(TippyPlugin);app.use(TippyPlugin,{tippyDefaults:{},// convenience to set tippy.js default props});
// or add them individuallyimport{TippyDirective,Tippy,TippySingleton}from'tippy.vue';app.directive('tippy',TippyDirective);app.component('tippy',Tippy);app.component('tippy-singleton',TippySingleton);importtippyfrom'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> <divv-tippy>Wow</div> <tippy>Cool</tippy> </div></template><script>import {Tippy,TippyDirective}from'tippy.vue'exportdefault { components: { Tippy }, directives: { tippy: TippyDirective }}</script>
// use the pluginapp.use(TippyVue);app.use(TippyVue,{tippyDefaults:{},// convenience to set tippy.js default props});
// or add them individuallyapp.directive('tippy',TippyVue.TippyDirective);app.component('tippy',TippyVue.Tippy);app.component('tippy-singleton',TippyVue.TippySingleton);tippy.setDefaultProps({// default tippy props});
Tippy.vue includes code completion files for IntelliJ IDEA, Vetur, and Volar.See the docs for details on how to use them.
Setting up an environment is very standard. Make sure you're on the latest version of yarn, then run:
yarn installyarn docs:dev
About
Nesting-free Tippy.js components for Vue 3