✨ Help support the maintenance of this package by sponsoring me.
Add tooltips to your Alpine 3.x components with a custom directive.
This package only supports Alpine v3.x.
This plugin adds a new x-tooltip to Alpine, alongside a bunch of modifiers for changing your tooltip's behaviour.
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 install @ryangjchandler/alpine-tooltipAdd 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();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" />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>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.
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.500x-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.cursorx-tooltip.cursor.xx-tooltip.cursor.initial |
on |
Change the trigger event for the tooltip. Default behaviour is mouseenter and focus. |
x-tooltip.on.clickx-tooltip.on.focusx-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 |
This projects follow the Semantic Versioning guidelines.
Copyright (c) 2021 Ryan Chandler and contributors
Licensed under the MIT license, see LICENSE.md for details.