---
layout: default
---

<div id="app">
    <div id="banner">
        <header>
            <h2>Vue Directive Tooltip</h2>
            <h4>a directive for Vue.js</h4>
        </header>
    </div>

<!-- installation -->
    <section id="installation">
        <div class="container">
            <header class="major">
                <h3>Installation</h3>
            </header>
            
            <h4>Using Webpack, Rollup, etc...</h4>
            <h5>1. using npm or yarn</h5>
            <p>
                install the script like so: <br>
                <prism lang="terminal">npm install vue-directive-tooltip --save</prism>
                or
                <prism lang="terminal">yarn add vue-directive-tooltip</prism>
            </p>

            <h5>2. use the script with Vue</h5>
            <prism lang="javascript">
// in your js file
import Vue from 'vue';
import Tooltip from 'vue-directive-tooltip';
import 'vue-directive-tooltip/css/index.css';
Vue.use(Tooltip);
            </prism>

            <h5>3. do not forget the css if you do not want to use the above import!</h5>
            <p>
                You can either get the raw css <a href="https://raw.githubusercontent.com/hekigan/vue-directive-tooltip/master/css/index.css" target="_blank">clicking here</a>
            </p>
            <p>
                or import the <b>css</b> from node_modules (in case of webpack, the <code>~</code> represents the node_modules folder): <br/>
                <prism lang="css">@import "~vue-directive-tooltip/css/index.css";</prism>
            </p>
            <p>
                or the scss directly: <br/>
                <prism lang="css">@import "~vue-directive-tooltip/src/css/index.scss";</prism>
            </p>
            
            <h4>Using script tag</h4>
            <p>
                When using ES5, don't forget to copy the css.  <br>
                raw css: <a href="https://raw.githubusercontent.com/hekigan/vue-directive-tooltip/master/css/index.css" target="_blank">download</a>
            </p>
            <prism>
&lt;link rel="stylesheet" href="https://unpkg.com/vue-directive-tooltip@latest/css/index.min.css"&gt;
&lt;script src="https://unpkg.com/vue@latest/dist/vue.js">&lt;/script&gt;
&lt;script src="https://unpkg.com/vue-directive-tooltip@latest/dist/vueDirectiveTooltip.min.js">&lt;/script&gt;
&lt;script>Vue.use(vueDirectiveTooltip);&lt;/script&gt;
            </prism>
        </div>
    </section>

<!-- change defaults -->
    <section id="defaults">
        <div class="container">
            <header>
                <h3>Change global default values</h3>
            </header>

            <p>
                Default values
            </p>
            <prism lang="javascript">
{
    delay: 200,
    placement: 'auto',
    class: '', // ex: 'tooltip-custom tooltip-other-custom'
    triggers: ['hover', 'focus'],
    offset: 5
}
            </prism>
            <p>
                If you have a need to change certain default value(s) for all tooltips:
            </p>
            <prism lang="javascript">
Vue.use(vueDirectiveTooltip, {
    delay: 500,
    placement: 'right',
    class: 'tooltip-red',
    triggers: ['hover'],
    offset: 0
});
            </prism>
        </div>
    </section>

<!-- usage -->
    <section id="usage">
        <div class="container">
            <header>
                <h3>Usage</h3>
            </header>
            
            <h4>Basic</h4>
            <p id="usage-basic">
                Example: <a href="#" @click.prevent v-tooltip="'basic one'">Tooltip</a>
            </p>
            <prism>&lt;span v-tooltip="'basic one'">Tooltip&lt;/span></prism>
            <p>
                Please be careful of the <strong>single quotes</strong> inside the <strong>double quote</strong>.
            </p>
            
            <h4>Using an options object</h4>
            <p id="usage-options">
                Example: <a href="#" @click.prevent v-tooltip="{ content: 'options object' }">Tooltip</a>
            </p>
            <prism>&lt;span v-tooltip="{ content: 'options object' }">Tooltip&lt;/span></prism>
            
            <h4>Referencing an HTML element</h4>
            <p id="usage-element">
                Example: <a href="#" @click.prevent v-tooltip="{ html: 'tooltipContent' }">the target is an html element</a>
            </p>
            <div id="tooltipContent">
                <span>this content is in an <strong>HTML</strong> tag</span>
            </div>
            <prism>
&lt;span v-tooltip="{ html: 'tooltipContent' }">the target is an html element&lt;/span>

&lt;div id="tooltipContent">
    &lt;p>this content is in an &lt;strong>HTML&lt;/strong> tag&lt;/p>
&lt;/div>
            </prism>
        </div>
    </section>

<!-- positioning -->
    <section id="positioning">
        <div class="container">
            <header>
                <h3>Positioning</h3>
            </header>
            
            <p>
                5 different positions are available: auto (default) | bottom | top | left | right
            </p>
            <p id="position-default">
                Default positioning: <a href="#" @click.prevent v-tooltip="'auto'">auto tooltip</a>
            </p>
            <prism>&lt;span v-tooltip="'auto positionning'">Tooltip&lt;/span></prism>
            
            <p id="position-bottom">
                Bottom positioning: <a href="#" @click.prevent v-tooltip.bottom="'bottom'">bottom tooltip</a>
            </p>
            <prism>&lt;span v-tooltip.bottom="'bottom'">bottom tooltip&lt;/span></prism>
            
            <p id="position-top">
                Top positioning: <a href="#" @click.prevent v-tooltip.top="'top'">top tooltip</a>
            </p>
            <prism>&lt;span v-tooltip.top="'top'">top tooltip&lt;/span></prism>

            <p id="position-left">
                Left positioning: <a href="#" @click.prevent v-tooltip.left="'left'">left tooltip</a>
            </p>
            <prism>&lt;span v-tooltip.left="'left'">left tooltip&lt;/span></prism>

            <p id="position-right">
                Right positioning: <a href="#" @click.prevent v-tooltip.right="'right'">right tooltip</a>
            </p>
            <prism>&lt;span v-tooltip.right="'right'">right tooltip&lt;/span></prism>
        </div>
    </section>
    
    <!-- positioning -->
    <section id="positioning-variant">
        <div class="container">
            <header>
                <h3>Positioning - Variants</h3>
            </header>
            
            <p>
                All above positions have 2 extra variants that you can use: start | end
            </p>
            <p id="position-bottom-start">
                Bottom Start positioning: <a href="#" @click.prevent v-tooltip.bottom.start="'Lorem ipsum dolor sit amet consectetur adipisicing elit. Est laborum eius similique quaerat neque omnis non animi fugiat dicta'">tooltip</a>
            </p>
            <prism>&lt;span v-tooltip.bottom.start="'bottom.start'">"bottom start" tooltip&lt;/span></prism>

            <p id="position-bottom-end">
                Bottom End positioning: <a href="#" @click.prevent v-tooltip.bottom.end="'Lorem ipsum dolor sit amet consectetur adipisicing elit. Est laborum eius similique quaerat neque omnis non animi fugiat dicta'">tooltip</a>
            </p>
            <prism>&lt;span v-tooltip.bottom.end="'bottom.end'">"bottom end" tooltip&lt;/span></prism>
        </div>
    </section>

<!-- delay -->
    <section id="delay">
        <div class="container">
            <header>
                <h3>Delay</h3>
            </header>

            <p>
                default: { delay: 200 }
            </p>
            <p>
                Example: <a href="#" @click.prevent v-tooltip.right="{content:'delayed by 1 second', delay: 1000}">Delayed Tooltip</a>
            </p>
            <prism>&lt;span v-tooltip="{content:'delayed by 1 second', delay: 1000}">Delayed Tooltip&lt;/span></prism>
        </div>
    </section>

<!-- offset -->
    <section id="offset">
        <div class="container">
            <header>
                <h3>Offset</h3>
            </header>

            <p>
                default: { offset: 5 }
            </p>
            <p>
                Example: <a href="#" @click.prevent v-tooltip.right="{content:'offset by 30px', offset: 30}">Offset Tooltip</a>
            </p>
            <prism>&lt;span v-tooltip="{content:'offset by 30px', offset: 30}">Offset Tooltip&lt;/span></prism>
        </div>
    </section>

<!-- events/triggers -->
    <section id="events-triggers">
        <div class="container">
            <header>
                <h3>Events / Triggers</h3>
            </header>
            
            <p>
                There are several options to trigger the display of the tooltip: <br>
                you can use a combination of these keywords: click | hover | focus
            </p>
            <p id="events-click">
                single event: <a href="#" @click.prevent v-tooltip.click="'Show on: click'">click trigger</a>
            </p>
            <prism>&lt;span v-tooltip.click="'Show on: click'">click trigger&lt;/span></prism>

            <p id="events-combi">
                or even a combination: <a href="#" @click.prevent v-tooltip.hover.focus="'Show on: hover.focus'">hover.focus triggers together</a>
            </p>
            <prism>&lt;span v-tooltip.hover.focus="'Show on: hover.focus'">hover.focus triggers together&lt;/span></prism>
            
            <p id="events-manual">
                By the default, the <code>click</code> trigger will close when clicking anywhere on the page. <br>
                In case you want the tooltip to close when clicking again on the same element, there is an extra option.
                click event: <a href="#" @click.prevent v-tooltip.click.manual="'click + manual trigger'">click + manual trigger</a>
            </p>
            <prism>&lt;span v-tooltip.click.manual="'click + manual trigger'">click + manual trigger&lt;/span></prism>
        </div>
    </section>

<!-- programmatic -->
    <section id="programmatic">
        <div class="container">
            <header>
                <h3>Programmatic</h3>
            </header>
            
            <p>
                If you do not want to use triggers and manage the tooltip visibility through Vue, you can! <br>
                For that, you need to use the modifier <code>.notrigger</code> + the options object attribute <code>visible</code> <br>
                <code>&lt;a v-tooltip.notrigger="{ content: '...', visible: visibility }"</code>
            </p>
            <p id="prog">
                <a @click.prevent v-tooltip.right.notrigger="{ content: 'change the visibility', visible: visibility }">change the visibility with the button below</a><br>
                <button @click="visibility = !visibility">
                    <span v-if="visibility">hide tooltip</span>
                    <span v-else>show tooltip</span>
                </button>
            </p>
            <prism>
&lt;template>
  &lt;div>
    &lt;a v-tooltip.notrigger="{ content: 'change the visibility', visible: visibility }">change the visibility with the button below&lt;/a>&lt;br>
    &lt;button @click="visibility = !visibility">
        &lt;span v-if="visibility">hide tooltip&lt;/span>
        &lt;span v-else>show tooltip&lt;/span>
    &lt;/button>
  &lt;/div>
&lt;/template>

&lt;script>
export default {
  data() {
    return {
        visibility: false
    };
  }
};
&lt;/script>
            </prism>
        </div>
    </section>

<!-- custom css / class -->
    <section id="custom-css">
        <div class="container">
            <header>
                <h3>Custom css / class</h3>
            </header>
            
            <p>
                Let's personalize a bit this tooltip! <br>
                Wants some red? Here is how you do it.
            </p>
            <p id="custom-class">
                Example: <a @click.prevent v-tooltip="{ content: 'custom class', class: 'tooltip-custom tooltip-other-custom' }">tooltip appearance</a>
            </p>
            <p>
                Full example on codepen: <a href="https://codepen.io/hekigan/pen/oebpPm" target="_blank">https://codepen.io/hekigan/pen/oebpPm</a>
            </p>
            <p>
                1. add somewhere in your css file the classes that you want to use. <br>
                Let's say... <code>.tooltip-custom</code>
            </p>
            <p>
                We have to account for the arrow color also depending on the tooltip's position.
            </p>
            <prism lang="css">
.vue-tooltip.tooltip-custom {
    background-color: red;
}

.vue-tooltip.tooltip-custom .tooltip-arrow {
    border-color: red;
}
            </prism>

            <p>
                2. in your directive options object, specify your css class name(s)
            </p>
            <prism>&lt;span v-tooltip="{ content: 'custom class', class: 'tooltip-custom tooltip-other-custom' }">custom tooltip&lt;/span></prism>
            
        </div>
    </section>

    <!-- special -->
    <section id="special">
        <div class="container">
            <header>
                <h3>Special modifiers</h3>
            </header>
            
            <p>
                Due to a <b>feature/bug</b> in mobile iOS/safari combo, users will have to tap twice to obtain a proper <b>click/tap</b>.
            </p>
            <p>
                Example: <a @click.prevent v-tooltip.ios="'tooltip on iOS'">iOS double tap killer</a>
            </p>
            <p>
                It's not a bug per say but a feature according to Safari's devs.
                This is a famous problem and I did a lot of digging to see what was involved.
            </p>
            <p>
                It is annoying to go around but at the same time I do understand the reason behind the implementation.
                First tap is for the <b>hover</b> event (either JS or CSS -this is important-), the second confirms that you want to <b>click</b> and not just hover.
            </p>
            <p>
                In the situation in which you just have a normal tooltip (let's say for a pagination), you want to just display the tooltip on the first tap and then click it on the second one.
                That's all well, but this tooltip lib can also be used to display interactive html content (like a menu). And in this case, it means trouble because you don't want to tap twice to activate a link.
            </p>
            <p>
                For this specific reason and because I don't want to have a breaking change, I think that the most elegant solution is to add a <code>.ios</code> modifier (like <code>.prevent</code> for example).
                What it will do is, on mobile safari on iOS, remove the hover event and substitute the click event for it. On other platform, it will retain the usual behaviour without any need for you to get involved.
                I did test a first implementation and it fixed the issue for me.
            </p>

            <prism>&lt;span v-tooltip.ios="'tooltip on iOS'">iOS double tap killer&lt;/span></prism>
            
        </div>
    </section>
</div>

    <script>
        Vue.use(vueDirectiveTooltip);

        Vue.component('Prism', {
            props: ['lang'],
            template: `<pre><code :class="language"><slot/></code></pre>`,
            computed: {
                language () {
                    return (this.lang) ? `language-${this.lang}` : 'language-html';
                }
            }
        });

        new Vue({ 
            el: '#app',
            data() {
                return { visibility: false };
            },
            components: {
                // Prism: window.Prism
            }
        });
    </script>