> ✨ Help support the maintenance of this package by [sponsoring me](https://github.com/sponsors/ryangjchandler). # Alpine Tooltip Add tooltips to your Alpine 3.x components with a custom directive. ![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/ryangjchandler/alpine-tooltip?label=version&style=flat-square) ![Build size Brotli](https://img.badgesize.io/ryangjchandler/alpine-tooltip/main/dist/cdn.min.js.svg?compression=gzip&style=flat-square&color=green) [![Monthly downloads via CDN](https://data.jsdelivr.com/v1/package/npm/@ryangjchandler/alpine-tooltip/badge)](https://www.jsdelivr.com/package/npm/@ryangjchandler/alpine-tooltip) > 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 ` ``` ### NPM ```bash npm install @ryangjchandler/alpine-tooltip ``` Add the `x-tooltip` directive to your project by registering the plugin with Alpine. ```js 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: ```html ``` ## Usage To create a tooltip, use the `x-tooltip` directive on an element. ```html
``` ### 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. ```html ``` 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](https://atomiks.github.io/tippyjs/). 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](https://atomiks.github.io/tippyjs/v6/themes/). | `x-tooltip.theme.light` | | `placement` | Change the placement / position of the tooltip. Find out more [here](https://atomiks.github.io/tippyjs/v6/all-props/#placement). | `x-tooltip.placement.top`, `x-tooltip.placement.bottom-start` | | `animation` | Change the animation used for the tooltip. Find out more [here](https://atomiks.github.io/tippyjs/v6/animations/). | `x-tooltip.animation.scale`, `x-tooltip.animation.perspective` | | `no-flip` | Disable Popper's default auto-flip behaviour. This allows you to set a placement with `.placement` and always enforce it. | `x-tooltip.placement.left.no-flip` | ### `$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. ```html ``` There's a couple of things going on here: 1. 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. 2. We tell Tippy to `allowHTML`. By default, the HTML will be rendered as plain text. 3. Tippy will append the actual tooltip element to the `document.body` by default. Since our `