✨ Help support the maintenance of this package by sponsoring me.
Alpine Tooltip
Add tooltips to your Alpine 3.x components with a custom directive.
This package only supports Alpine v3.x.
About
This plugin adds a new x-tooltip
to Alpine, alongside a bunch of modifiers for changing your tooltip's behaviour.
Installation
CDN
Include the following <script>
tag in the <head>
of your document, just before Alpine.
<script
src="https://cdn.jsdelivr.net/npm/@ryangjchandler/[email protected]/dist/cdn.min.js"
defer
></script>
NPM
npm install @ryangjchandler/alpine-tooltip
Add the x-tooltip
directive to your project by registering the plugin with Alpine.
import Alpine from "alpinejs";
import Tooltip from "@ryangjchandler/alpine-tooltip";
Alpine.plugin(Tooltip);
window.Alpine = Alpine;
window.Alpine.start();
CSS
You will also need to include the following CSS in your document:
<link rel="stylesheet" href="https://unpkg.com/tippy.js@6/dist/tippy.css" />
Usage
To create a tooltip, use the x-tooltip
directive on an element.
<div x-data="{ tooltip: 'This is crazy!' }">
<button x-tooltip="tooltip">Hover for info!</button>
</div>
Raw text
If you don't want to bind your tooltip's content to a data property in your Alpine component, you can add the .raw
modifier to the directive and set the content using the directive expression instead.
<button x-data x-tooltip.raw="Hello, world!">
Raw Tooltip
</button>
The expression / text inside of the directive will be used as the tooltip and it will only be initialised and configured once.
Disabling the tooltip
If you wish to disable the tooltip you can set the data property to a falsy value, i.e. an empty string, null
, undefined
or false
. If you wish to re-enable the tooltip, just update the data property to a truthy expression and the plugin will call the enable()
method on the Tippy instance.
Modifiers
The x-tooltip
directive is powered by Tippy.js. Tippy has a lot of different configuration options, some of which can be controlled via modifiers on the x-tooltip
directive.
Modifier | Description | Usage |
---|---|---|
duration |
Change the transition duration (ms) of the toolip. | x-tooltip.duration.500 |
delay |
Change the transition delay (ms) of the tooltip. | x-tooltip.delay.500 x-tooltip.delay.500-0 |
cursor |
Determines if the tooltip follows the user's cursor. Default behaviour will follow cursor around target element. x will follow the cursor horizontally.initial will place the cursor at the user's cursor on trigger. |
x-tooltip.cursor x-tooltip.cursor.x x-tooltip.cursor.initial |
on |
Change the trigger event for the tooltip. Default behaviour is mouseenter and focus . |
x-tooltip.on.click x-tooltip.on.focus x-tooltip.on.mouseenter |
arrowless |
Hide the "arrow" on the tooltip. | x-tooltip.arrowless |
html |
Allow HTML inside of the tooltip. | x-tooltip.html |
interactive |
Allow the user to interact with the tooltip (prevent it from disappearing). | x-tooltip.interactive |
border |
Change the size of the invisible border (px) around the tooltip that will prevent it from hiding when the cursor leaves it. | x-tooltip.interactive.border.30 |
debounce |
Change the time (ms) to debounce the interactive hide handler when the cursor leaves the tooltip. | x-tooltip.interactive.debounce.500 |
max-width |
Change the max-width (px) of the tooltip. |
x-tooltip.max-width.500 |
theme |
Change the theme of the tooltip. Find out more here. | x-tooltip.theme.light |
placement |
Change the placement / position of the tooltip. Find out more here. | x-tooltip.placement.top , x-tooltip.placement.bottom-start |
animation |
Change the animation used for the tooltip. Find out more here. | x-tooltip.animation.scale , x-tooltip.animation.perspective |
$tooltip
As well as the x-tooltip
directive, this package also provides a $tooltip
magic function that you can use to manually instantiate a tooltip.
<button @click="$tooltip('Hello, world!')">
When you click on this button, the tooltip will show and be hidden 2 seconds later.
Configuring the timeout
If you would like the tooltip to show for longer than 2 seconds, you can provide an object as the second argument to the $tooltip
magic function.
<button @click="$tooltip('Hello, world!', { timeout: 5000 })">
The timeout should be in milliseconds (seconds * 1000
).
Tippy configuration
The second argument to $tooltip
should be an object. This object accepts all Tippy.js configuration options, found in the docs.
The magic variable will automatically set the content
property to the value of the first argument, as well as the trigger
property (manual
). You're free to specify any other properties supported by Tippy.
<button @click="$tooltip('Hello, world!', { delay: 500 })">
Using another element for content
This package allows you to provide a raw configuration object for Tippy. This means you can use an HTML element to render the tooltip's content:
<div x-data="{ message: 'Hello, world!' }">
<template x-ref="template">
<p x-text="message"></p>
</template>
<button x-tooltip="{
content: () => $refs.template.innerHTML,
allowHTML: true,
appendTo: $root
}">
Show message!
</button>
</div>
There's a couple of things going on here:
- We provide a callback to the
content
property which will be invoked before Tippy renders the tooltip. This allows us to use dynamic HTML content as the content inside of the tooltip. - We tell Tippy to
allowHTML
. By default, the HTML will be rendered as plain text. - Tippy will append the actual tooltip element to the
document.body
by default. Since our<template>
contains Alpine directives, placing those outside of our actual Alpine component will result in errors. To fix this, Tippy will instead append the element to the$root
element which is the element where our Alpine component starts (a<div>
in this case). This allows us to use Alpine directives inside of our template for data binding, etc.
Note If you wish to use buttons or other interactive elements inside of your content, you should add
interactive: true
to the object.
Versioning
This projects follow the Semantic Versioning guidelines.
License
Copyright (c) 2021 Ryan Chandler and contributors
Licensed under the MIT license, see LICENSE.md for details.