• Stars
    star
    315
  • Rank 132,951 (Top 3 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 3 years ago
  • Updated 8 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Add tooltips to your Alpine 3.x components with a custom directive.

Help support the maintenance of this package by sponsoring me.

Alpine Tooltip

Add tooltips to your Alpine 3.x components with a custom directive.

GitHub tag (latest by date) Build size Brotli Monthly downloads via CDN

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:

  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 <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.

More Repositories

1

spruce

A lightweight state management layer for Alpine.js. 🌲
JavaScript
911
star
2

orbit

A flat-file database driver for Eloquent. 🗄
PHP
849
star
3

alpine-clipboard

Simply copy to the users clipboard in your Alpine.js components. 📋
JavaScript
348
star
4

laravel-cloudflare-turnstile

A simple package to help integrate Cloudflare Turnstile.
PHP
227
star
5

laravel-comments

A dead-simple comments package for Laravel.
PHP
211
star
6

blade-cache-directive

Cache chunks of your Blade markup with ease. 🔪
PHP
196
star
7

alpine-hooks

A collection of hooks for use with Alpine.js.
JavaScript
178
star
8

laravel-feature-flags

An opinionated feature flags package for Laravel.
PHP
167
star
9

filament-navigation

Build structured navigation menus in Filament.
PHP
161
star
10

prettier-plugin-blade

Adds support for Blade templates to Prettier. (work in progress)
TypeScript
138
star
11

filament-profile

A simple profile management page for Filament. ✨
PHP
100
star
12

bearer

Minimalistic token-based authorization for Laravel API endpoints.
PHP
83
star
13

blade-tabler-icons

A Blade icon pack for the Tabler icon set.
PHP
76
star
14

forge-previewer

Create preview deployments for pull requests with Laravel Forge.
PHP
74
star
15

blade-capture-directive

Create inline partials in your Blade templates with ease.
PHP
66
star
16

alpine-mask

A clean integration between Cleave.js and Alpine. ✨
JavaScript
60
star
17

filament-progress-column

Add a progress bar column to your Filament tables.
PHP
60
star
18

cpx

Quickly execute Composer package binaries from anywhere. ⚡️
PHP
58
star
19

using

Enforced disposal of objects in PHP. 🐘
PHP
53
star
20

is-php-dead.lol

Is PHP dead?
PHP
48
star
21

filament-feature-flags

Control your Laravel feature flags through a clean Filament interface.
PHP
47
star
22

lexical

Quickly build lexers in PHP.
PHP
44
star
23

laravel-uuid

A small package for adding UUIDs to Eloquent models.
PHP
40
star
24

color

A simple Color object for PHP packages and applications. 🎨
PHP
38
star
25

cursed-html

Who said HTML wasn't a programming language?
JavaScript
37
star
26

filament-tools

Add a general-purpose tools page to your Filament project. 🛠
PHP
37
star
27

standalone-blade

Use Laravel's Blade templating engine outside of Laravel.
PHP
36
star
28

phpast.com

A web tool to explore the ASTs generated by PHP-Parser.
PHP
35
star
29

laravel-helpers

A collection of helper functions that I use across my projects.
PHP
34
star
30

laravel-json-settings

Store your Laravel application settings in an on-disk JSON file. ⚙️
PHP
31
star
31

lagoon

A dynamic, weakly-typed and minimal scripting language. 🏞
Rust
29
star
32

computed-properties

A small package to add computed properties to any PHP class. 🐘
PHP
27
star
33

fern

Persisted global stores for Alpine 3.x.
JavaScript
26
star
34

laravel-slug

Simple slugs for your Laravel models.
PHP
25
star
35

skeleton-laravel

PHP
25
star
36

x-else

An `x-else` directive for use in Alpine components. ✨
JavaScript
25
star
37

filament-minimal-tabs

A clean and minimal design for the Tabs component in Filament.
CSS
24
star
38

ryangjchandler.co.uk

My personal website, blog and project documentation.
PHP
22
star
39

laravel-expose

A clean integration between Laravel and Expose. ⚡️
PHP
21
star
40

alpine-parent

Adds a handy $parent magic property to your Alpine components.
JavaScript
18
star
41

alpine-toggle

Quickly toggle / negate a property in your Alpine.js components.
JavaScript
17
star
42

puny

Make unit testing in PHP simpler again. 👌
PHP
17
star
43

laravel-orphan-controller

Quickly identify controller methods with no route in your Laravel applications.
PHP
16
star
44

filament-log

A simplistic log viewer for your Filament apps.
PHP
15
star
45

git

A small PHP wrapper for Git. ✨
PHP
15
star
46

filament-user-resource

A simple resource for managing users in Filament.
PHP
14
star
47

laravel-make-user

Quickly create `User` models with Artisan. ⚡️
PHP
14
star
48

fn-inspector

A utility package that helps inspect functions in PHP.
PHP
14
star
49

stencil

A simple template engine for PHP written for a tutorial blog post.
PHP
14
star
50

tonic

An elegant language for script-kiddies and terminal squatters.
Rust
12
star
51

bytes

A class to help convert bytes into other units (kb, mb, etc).
PHP
12
star
52

laravel-make-view

A simple `make:view` command for Laravel applications.
PHP
10
star
53

laravel-bunny-fonts

Manage Bunny Fonts programatically in your Laravel projects.
PHP
10
star
54

laravel-rql

I don't like writing queries for CSV exports.
PHP
9
star
55

filament-color-palette

Let users pick a color from a fixed list of options.
PHP
8
star
56

fakeinator

Quickly generate CSV files full of fake data. 💽
HTML
7
star
57

container

A service container for PHP.
PHP
7
star
58

proxy

Proxy method and property interactions in PHP. ⚡️
PHP
7
star
59

laravel-auto-validate-models

A small package to auto-validate your Laravel models.
PHP
7
star
60

krypt

Share short-lived encrypted text messages with others.
PHP
6
star
61

uptime-checker

My personal uptime checker powered by Filament. ⚡️
PHP
6
star
62

blade-lint

Validate and analyse Blade templates in your Laravel project.
PHP
6
star
63

repository

📦 A dead-simple repository class for use with Laravel.
PHP
5
star
64

rgjc.me

A disgustingly simple URL shortener powered by Laravel. 📶
PHP
5
star
65

laravel-restore-mix

A small CLI script that removes Vite in favour of Laravel Mix.
PHP
5
star
66

microphp

A small subset of PHP implemented in Rust. 🐘
Rust
5
star
67

rss-reader

An RSS reader application built with Laravel.
PHP
5
star
68

forge-previewer-action

A quick and easy way to get Forge Previewer running in GitHub Actions.
Dockerfile
5
star
69

paddle-demultiplexer

A simple serverless function to demultiplex Paddle webhooks.
TypeScript
4
star
70

filament-data-studio

Low configuration exports and data analysis for Filament.
PHP
4
star
71

phpbyexample.dev

A simple introduction to PHP with annotated code snippets.
CSS
4
star
72

template-rust-cli

A template for command-line Rust projects.
Python
4
star
73

peso

An elephant-ish esoteric programming language inspired by Brainf*ck.
PHP
4
star
74

notepal

My personal note-taking application.
PHP
3
star
75

typewrite.cc

A bring-your-own-email-first newsletter service. ✨
PHP
3
star
76

filament-plugin-search

Add a page to your Filament panel to search for plugins.
PHP
3
star
77

filament-simple-repeater

A single-field repeater for Filament. ⚡️
PHP
3
star
78

php-ffi-example

An example of using PHP + FFI with C, Rust and Go.
PHP
3
star
79

advent-of-code

Advent of Code Solutions in PHP
PHP
3
star
80

c-in-php

An incredibly cursed C interpreter written in PHP.
PHP
3
star
81

laravel-worldwide-demo

The demo used for my talk at October's Laravel Worldwide Meetup.
PHP
2
star
82

rook-lang

A small scripting language running on V8.
Rust
2
star
83

curl-to-laravel-http

PHP
2
star
84

filament-passwordless-login

PHP
2
star
85

60-second-laravel

The demo application used in the 60 Second Laravel series.
PHP
2
star
86

pl

A toy language implemented in Rust. 🦀
Rust
2
star
87

filament-plausible-page

Embed your site's Plausible dashboard inside of Filament.
PHP
2
star
88

laravel-slack-webhook

A fluent package for building Slack webhook payloads.
PHP
2
star
89

mathexpr

A tiny math expression evaluator written in PHP.
PHP
2
star
90

alpinejs-mobile

Swift
2
star
91

polling-app

A simple polling application built with the TALL stack. 🗼
PHP
2
star
92

laravel-restore-command

An Artisan command to quickly restore soft-deleted models. ⚡
PHP
2
star
93

php-parser-specs

A set of specification tests for PHP parsers, used to improve compliance and acceptance.
PHP
2
star
94

phiki

Syntax highlighting powered by TextMate grammars in PHP.
PHP
2
star
95

laravel-synchro

Easily sync and anonymise your data between environments.
PHP
2
star
96

blade-validator

Run rudimentary linting checks on your Blade templates.
PHP
1
star
97

expr

A powerful expression engine designed for business rules and sandboxed execution. 🔡
PHP
1
star
98

blade-in-directive

A tidy conditional Blade directive for checking if something is in an array.
PHP
1
star
99

chains

Gold, silver, diamonds, tiny ol' JavaScript framework.
JavaScript
1
star
100

filament-sanctum

Manage your Sanctum tokens inside of Filament. ✨
PHP
1
star