How to install a customizable Vue tooltip component to create help text and abbreviations
Tags: vue, tooltip, vuepress, tutorial
Published: 2020-08-21 12:19:52

---
title: How to install a customizable Vue tooltip component to create help text and abbreviations
published: true
description: Tooltips are a great way to provide additional info; this post walks you through how to install a reusable tooltip component to use in your Vue projects.
tags: vue, tooltip, vuepress, tutorial
canonical_url: https://www.adamdehaven.com/blog/how-to-install-a-customizable-vue-tooltip-component-to-create-help-text-and-abbreviations/
cover_image: https://dev-to-uploads.s3.amazonaws.com/i/ewsis7fdhjwngsnf9jv7.png
---

Tooltips are a great way to provide additional information when a user hovers over an element on a page. In this post, I'll walk you through installing the same tooltip component I wrote for my site via a custom Vue plugin that you can utilize in your own project!

<!-- more -->

## The tooltip component

In Vue applications, it's common practice to define reusable components that can be repeated throughout your project. Since components are reusable Vue instances, they can be used again and again, as many times as you want, even on the same page. Each instance of the component will maintain its own, separate data bindings and attributes.

The reusable vue tooltip component we will be installing has two main use-cases that are both accomplished with the same `<VueCustomTooltip>` element:

1. Dynamic tooltips for other structured elements on the page.
2. Tooltips for providing additional information or abbreviations for text on the page.

Our tooltip component can be used in any project that utilizes Vue, including VuePress sites like this one! :tada: Before diving into the code, let's take a look at a couple examples of how we can use the plugin.

### Tooltips for other elements

The first example, a tooltip for other elements on the page, can be used to provide the user with additional information related to actions that can be taken for a given element.

For example, the button below shows a tooltip that indicates what clicking the button will do (the tooltip is sticky for demo purposes):

![Vue customizable tooltip component with twitter button](https://dev-to-uploads.s3.amazonaws.com/i/tk33tkkv3kyvcxh78jqi.png)

### Tooltips for text

Tooltips added to text within the page can be used to provide contextual information. These helpful tooltips can define acronyms or abbreviations, or even provide help text that corresponds to the word or phrase already being displayed.

For example, the underlined text below is an acronym that, when hovered, will display the definition for the abbreviated text (again, the tooltip is sticky for demo purposes).

![Vue tooltip component with abbreviation help text](https://dev-to-uploads.s3.amazonaws.com/i/ffwvcpswzpphwyuus3ub.png)

Now that we've taken a look at the different use-cases for the plugin, let's install it in our project.

## Installation

``` sh
# With npm
npm install @adamdehaven/vue-custom-tooltip

# or Yarn
yarn add @adamdehaven/vue-custom-tooltip
```

### Vue.js (Global Install - Recommended)

It is recommended to install the plugin in your Vue project's entry file. For projects created with [`@vue/cli`](https://cli.vuejs.org/), this is likely your `main.js` file where you are already importing `Vue`.

``` js
// main.js (or your Vue entry file)

// Import Vue... you're probably already doing this
import Vue from 'vue'

// Import the tooltip component before calling 'new Vue()'
import VueCustomTooltip from '@adamdehaven/vue-custom-tooltip'

// Install the plugin using ONE of the options below:
// --------------------------------------------------

// 1. Install with default options
Vue.use(VueCustomTooltip)

// ===== OR  =====

// 2. Install with custom options (defaults shown)
Vue.use(VueCustomTooltip, {
    name: 'VueCustomTooltip',
    color: '#fff',
    background: '#000',
    borderRadius: 12,
    fontWeight: 400,
})
```

### VuePress (Standalone Plugin - Recommended)

I have released a standalone VuePress plugin that wraps this component into an actual VuePress Plugin installable through the `.vuepress/config.js` or `.vuepress/theme/index.js` file. If you'd rather use the standalone plugin in your VuePress project, [head over to the `vuepress-plugin-custom-tooltip` repository](https://github.com/adamdehaven/vuepress-plugin-custom-tooltip), or follow these simple install instructions instead:

``` sh
# With npm
npm install @adamdehaven/vuepress-plugin-custom-tooltip

# or Yarn
yarn add @adamdehaven/vuepress-plugin-custom-tooltip
```

You can use the plugin by installing it in your `.vuepress/config.js` file, as shown here:

``` js
// .vuepress/config.js
module.exports = {
    // Install the plugin using ONE of the options below:
    // --------------------------------------------------

    // 1. Install with default options
    plugins: [
        '@adamdehaven/vuepress-plugin-custom-tooltip',
    ],

    // ===== OR  =====

    // 2. Install with custom options (defaults shown)
    plugins: [
        ['@adamdehaven/vuepress-plugin-custom-tooltip', {
            name: 'VueCustomTooltip',
            color: '#fff',
            background: '#000',
            borderRadius: 12,
            fontWeight: 400,
        }],
    ],
}
```

Alternatively, if you are using a theme, you may install in your `.vuepress/theme/index.js` file:

``` js
// .vuepress/theme/index.js
module.exports = (options, ctx) => {
    return {
        // Install the plugin using ONE of the options below:
        // --------------------------------------------------

        // 1. Install with default options
        plugins: [
            '@adamdehaven/vuepress-plugin-custom-tooltip',
        ],

        // ===== OR  =====

        // 2. Install with custom options (defaults shown)
        plugins: [
            ['@adamdehaven/vuepress-plugin-custom-tooltip', {
                name: 'VueCustomTooltip',
                color: '#fff',
                background: '#000',
                borderRadius: 12,
                fontWeight: 400,
            }],
        ],
    }
}
```

### VuePress (Global Install)

For [VuePress](https://vuepress.vuejs.org/) projects, the `theme/enhanceApp.js` is a good location to initialize plugins.

``` js
// theme/enhanceApp.js

// Import Vue... you're probably already doing this
import Vue from 'vue'

// Import the tooltip component
import VueCustomTooltip from '@adamdehaven/vue-custom-tooltip'

export default ({
    Vue, // the version of Vue being used in the VuePress app
    options, // the options for the root Vue instance
    router, // the router instance for the app
    siteData, // site metadata
    isServer, // is this enhancement applied in server-rendering or client
}) => {
    // ...apply enhancements to the app

    // Install the plugin using ONE of the options below:
    // --------------------------------------------------

    // 1. Install with default options
    Vue.use(VueCustomTooltip)

    // ===== OR  =====

    // 2. Install with custom options (defaults shown)
    Vue.use(VueCustomTooltip, {
        name: 'VueCustomTooltip',
        color: '#fff',
        background: '#000',
        borderRadius: 12,
        fontWeight: 400,
    })
}
```

### In-Component Install

Alternatively, you may install the component directly within a single file in your project; however, you will not be able to customize the `Vue.use()` options.

``` html
<!-- Single file component -->

<script>
// Import the tooltip component (no options available)
import VueCustomTooltip from '@adamdehaven/vue-custom-tooltip'

// .vue file default export
export default {
    // Register the component
    components: {
        VueCustomTooltip,
    },
}
</script>
```

**NOTE**: Installing inside a single component (instead of globally) does not allow you to customize the [Plugin Options](#options); however, you may still utilize all [`props`](#props) on the `<VueCustomTooltip>` element.

### CDN

Import the tooltip component after importing Vue in your file after importing Vue. Installing via CDN does not allow for customizing [Plugin Options](#options).

Installing via the CDN requires using the kebob-case component name.

``` html
<!-- Import Vue -->
<script src="https://unpkg.com/vue/dist/vue.js"></script>
<!-- Import tooltip component -->
<script src="https://unpkg.com/@adamdehaven/vue-custom-tooltip"></script>

<!-- Then simply use the component -->
<p>This is a <vue-custom-tooltip label="Neat!" underlined>tooltip</vue-custom-tooltip>.</p>
```

### Manual

Download `dist/vue-custom-tooltip.min.js` and include it in your file after importing Vue. Installing manually does not allow for customizing [Plugin Options](#options).

Installing manually requires using the kebob-case component name.

``` html
<!-- Import Vue -->
<script src="https://unpkg.com/vue/dist/vue.js"></script>
<!-- Import tooltip component -->
<script src="/path/to/vue-custom-tooltip.min.js"></script>

<!-- Then simply use the component -->
<p>This is a <vue-custom-tooltip label="Neat!" underlined>tooltip</vue-custom-tooltip>.</p>
```

## Usage

As we already went over, there are several different ways to use the component once installed. Here are a few examples:

``` html
<!-- Basic -->
What is <VueCustomTooltip label="This is a tooltip">a tooltip</VueCustomTooltip>?

<!-- With Options -->
What is <VueCustomTooltip label="This is a tooltip" position="is-bottom" abbreviation sticky>a tooltip</VueCustomTooltip>?

<!-- With element(s) -->
<VueCustomTooltip label="View @adamdehaven on Twitter">
    <a class="button" href="https://twitter.com/adamdehaven">
        <span class="icon icon-twitter"></span>
        <span>Twitter</span>
    </a>
</VueCustomTooltip>
```

## Options

Pass any of the options listed below to `Vue.use(VueCustomTooltip, {...})` to customize the plugin for your project *(not available with [in-component installation](#in-component-install))*.

**A note on options tied to CSS properties**: The `color`, `background`, `borderRadius`, and `fontWeight` attributes listed below are set on the psuedo element using [CSS Variables (Custom Properties)](https://caniuse.com/#feat=css-variables), meaning they will fallback to their default values in unsupported browsers (e.g. Internet Explorer).

### `name`

- Type: `String`
- Default: `VueCustomTooltip`

Customize the name of the component you will use in your project. **Camel-case names are preferred**, as this allows for camel-case or kebob-case usage within your project.

``` js
Vue.use(VueCustomTooltip, {
    name: 'SuperCoolTooltip', // camel-case preferred
})
```

If you registered the name using camel-case, you can reference the tooltip component via camel-case *or* kebob-case:

``` html
<!-- Default name (user did not pass the 'name' option) -->

<!-- camel-case -->
Nice <VueCustomTooltip label="Neat!">tooltip</VueCustomTooltip>!
<!-- kebob-case -->
Nice <vue-custom-tooltip label="Neat!">tooltip</vue-custom-tooltip>!

<!-- Custom name (allows user to rename component) -->

<!-- camel-case -->
Nice <SuperCoolTooltip label="Neat!">tooltip</SuperCoolTooltip>!
<!-- kebob-case -->
Nice <super-cool-tooltip label="Neat!">tooltip</super-cool-tooltip>!
```

### `color`

- Type: `HEX Color`
- Default: `#fff`

Customize the color of the text displayed in the tooltip.

``` js
Vue.use(VueCustomTooltip, {
    color: '#c1403d', // 3 or 6 digit HEX color, including a leading hash (#)
})
```

### `background`

- Type: `HEX Color`
- Default: `#000`

Customize the background color (and the `underlined` text color) of the tooltip.

``` js
Vue.use(VueCustomTooltip, {
    background: '#1b2735', // 3 or 6 digit HEX color, including a leading hash (#)
})
```

### `borderRadius`

- Type: `Number`
- Default: `12`

Customize the border-radius of the tooltip. Must be an integer.

``` js
Vue.use(VueCustomTooltip, {
    borderRadius: 4,
})
```

### `fontWeight`

- Type: `Number`
- Default: `400`

Customize the font-weight of the tooltip text. Must be an integer that is a multiple of 100, between 100 - 900.

``` js
Vue.use(VueCustomTooltip, {
    fontWeight: 700,
})
```

## Props

In addition to the [Plugin Options](#options) above, you may also pass props to the component itself to customize both the look and behavior of the tooltip element.

Props that accept a Boolean value may be passed simply by adding the attribute to the component tag, if a `true` value is desired. See the `sticky` example here:

``` html
<VueCustomTooltip label="Tooltip" sticky>text/element</VueCustomTooltip>
```

All other props may be passed as normal attributes (if the corresponding value is a String, like the `label` prop, shown above) or with `v-bind` directives, as shown here:

``` html
<VueCustomTooltip :label="element.helpText" :sticky="false">text/element</VueCustomTooltip>
```

All available props for the tooltip component are listed below:

### `label`

- Type: `String`
- Default: `null`

The text that will display inside the tooltip. If the value for `label` is null, the tooltip will not be displayed.

You may **not** pass HTML to the label prop.

### `active`

- Type: `Boolean`
- Default: `true`

Determines whether the tooltip should display when hovered, or if the [`sticky`](#sticky) prop is present, if the tooltip should be visible.

### `position`

- Type: `String`
- Value: `is-top / is-bottom / is-left / is-right`
- Default: `is-top`

The position of the tooltip in relation to the text/element it is surrounding.

### `abbreviation`

- Type: `Boolean`
- Default: `false`

Swaps out the component's standard `<span>` element with a semantically-correct `<abbr>` element, and sets the [`underlined`](#underlined) prop to `true`. This is useful when adding a tooltip to text within a page's content where you want to provide additional context to a word or phrase, or provide a definition of a word or acronym.

``` html
VuePress pages are served as an <VueCustomTooltip label="Single Page Application" abbreviation>SPA</VueCustomTooltip>.
```

### `sticky`

- Type: `Boolean`
- Default: `false`

Determines if the tooltip should always be displayed (including on component load/mounting), regardless of the element being hovered.

### `underlined`

- Type: `Boolean`
- Default: `false`

Add a dotted border under the contained text (the same color as the [background](#background) HEX value). This value is automatically set to `true` if the [`abbreviation`](#abbreviation) prop is set to `true`.

### `multiline`

- Type: `Boolean`
- Default: `false`

Allows the tooltip text to wrap to multiple lines as needed. Can be used in conjunction with the [`size`](#size) prop to adjust the width of the tooltip.

### `size`

- Type: `String`
- Value: `is-small / is-medium / is-large`
- Default: `is-medium`

The width of the tooltip, if the [`multiline`](#multiline) prop is set to `true`.

## Adding Custom Classes & Styles

Just like any other Vue component, you can add classes or styles directly to the component tag that will be applied to the rendered `<span>` tag (or `<abbr>` tag, if `abbreviation` is set to `true`).

``` html
<!-- Tooltip component with custom classes and styles -->
<VueCustomTooltip class="your-class" :class="{ 'dynamic-class': isDynamic }" :style="{ display: 'inline' }" label="Neat">text</VueCustomTooltip>
```

This is extremely helpful if you want to extend functionality or tooltip styles within your project, which allows you to tweak things like the display behavior of the tooltip element.

The tooltip component is rendered as a `display: inline-block` element by default; however, you can override this by binding styles directly to the component, as shown above.

## How easy was that?!

Installing the custom Vue tooltip plugin is an easy way to provide a global component for your Vue project.

Tell me what you think below in the [comments](#comments), and let me know if you're using the plugin!