@artusdev/tailwind-underlines

Advanced animated underline utilities for Tailwind CSS v4.

✨ Features

• 🎨 Fully Customizable - Control thickness, duration, timing, offset, and color
• 🔄 Bidirectional Control - Independent in/out animation directions
• 🎯 Pure CSS - Zero JavaScript dependencies
• 🌳 Tree-Shakeable - Only includes classes you use
• ✨ Tailwind v4 Ready - Native support for arbitrary values and theme tokens
• ♿ Accessible - Works with all Tailwind variants (focus, group-hover, etc.)

📦 Installation

npm install @artusdev/tailwind-underlines

🚀 Quick Start

1. Import the plugin in your CSS:

@import "@artusdev/tailwind-underlines";

2. Add to your HTML:

<a class="underline-base hover:underline-expanded"> Hover me </a>

That's it! You now have a beautiful animated underline.

📖 How It Works

The plugin uses a two-class pattern:

Class	Purpose
underline-base	Sets up the underline container, variables, and collapsed state
[variant]:underline-expanded	Triggers the underline animation (e.g., hover:, focus:, group-hover:)

🎨 Customization

Direction

Simple (Bidirectional)

Same direction for both enter and exit animations:

Class	Effect
underline-left	Left → Right (default)
underline-right	Right → Left
underline-center	Center → Outward

<a class="underline-base underline-center hover:underline-expanded"> Center expand </a>

Advanced (Independent Control)

Control entry and exit directions separately - 9 possible combinations:

Enter From	Exit To	Classes
Left	Right	underline-in-left underline-out-right
Center	Left	underline-in-center underline-out-left
Right	Center	underline-in-right underline-out-center

<a class="underline-base underline-in-left underline-out-right hover:underline-expanded">
    Enter left, exit right
</a>

Thickness

Type	Example	Output
Theme tokens	underline-thickness-thin	1px
	underline-thickness-normal	2px (default)
	underline-thickness-thick	4px
Bare integers	underline-thickness-5	5px
Arbitrary values	underline-thickness-[0.5rem]	0.5rem

Duration

Type	Example	Output
Theme tokens	underline-duration-fast	150ms
	underline-duration-normal	250ms (default)
	underline-duration-slow	500ms
Bare integers	underline-duration-1000	1000ms
Arbitrary values	underline-duration-[1.5s]	1.5s

Timing Functions

Type	Example	Effect
Theme presets	underline-timing-linear	Linear
	underline-timing-ease	Ease
	underline-timing-ease-in	Ease-in
	underline-timing-ease-out	Ease-out
	underline-timing-ease-in-out	Ease-in-out (default)
	underline-timing-bounce	Elastic bounce
	underline-timing-spring	Spring overshoot
Arbitrary	underline-timing-[cubic-bezier(0.4,0,0.2,1)]	Custom curve

Offset

Control vertical positioning. Note: Positive = down, negative = up.

Pattern	Example	Result
Bare integers	underline-offset-3	3px (down)
Arbitrary	underline-offset-[0.5rem]	0.5rem (down)
Negative prefix	-underline-offset-3	-3px (up)
Negative arbitrary	-underline-offset-[0.5rem]	-0.5rem (up)

Color

Supports all tailwindcss colors, your custom colors and arbitrary color values (defaults to currentColor):

<a class="underline-base underline-color-[#3b82f6] hover:underline-expanded"> Custom color </a>

💡 Examples

Basic

<a class="underline-base hover:underline-expanded"> Hover me </a>

Centered Fast Animation

<a class="underline-base underline-center underline-duration-fast hover:underline-expanded">
    Quick center expand
</a>

Button with Bounce Effect

<button
    class="underline-base underline-thickness-thick underline-timing-bounce active:underline-expanded"
>
    Click me
</button>

Complex Styling

<a
    class="underline-base underline-thickness-[8px] underline-duration-[2s]
          underline-color-[#3b82f6] underline-in-left underline-out-right
          hover:underline-expanded"
>
    Fully customized
</a>

Navigation Menu

<nav>
    <a class="group" href="/about">
        <span class="underline-base underline-center group-hover:underline-expanded"> About </span>
    </a>
</nav>

Accessible Focus State

<a class="underline-base focus:underline-expanded focus-visible:outline-2"> Tab to focus </a>

🎨 Extending the Theme

Add custom tokens in your CSS:

@theme {
    --underline-thickness-hairline: 0.5px;
    --underline-duration-ultra-fast: 75ms;
    --underline-timing-elastic: cubic-bezier(0.68, -0.55, 0.27, 1.55);
}

Use them like built-in tokens:

<a
    class="underline-base underline-thickness-hairline underline-duration-ultra-fast underline-timing-elastic hover:underline-expanded"
>
    Custom theme
</a>

🔧 API Reference

Utilities

Utility	Description	Default
underline-base	Base setup (required)	-
underline-expanded	Shows the underline	-
underline-left	Left to right	✓
underline-right	Right to left	-
underline-center	Center outward	-
underline-in-*	Entry direction	left
underline-out-*	Exit direction	left
underline-thickness-*	Thickness	2px (normal)
underline-duration-*	Animation duration	250ms (normal)
underline-timing-*	Timing function	ease-in-out
underline-offset-*	Vertical offset (down)	0px
-underline-offset-*	Vertical offset (up)	-
underline-color-*	Color	currentColor

CSS Variables

You can also control underlines via CSS custom properties:

.my-link {
    --underline-thickness: 3px;
    --underline-duration: 500ms;
    --underline-timing: cubic-bezier(0.4, 0, 0.2, 1);
    --underline-offset: 2px; /* positive = down, negative = up */
    --underline-color: #3b82f6;
    --underline-origin-in: left;
    --underline-origin-out: right;
}

⚙️ How It Works

The plugin uses CSS transforms for GPU-accelerated animations:

1. underline-base creates a pseudo-element (::after) scaled to 0 width
2. underline-expanded scales it to full width (scaleX(1))
3. Transform origin controls the animation direction
4. CSS custom properties enable runtime customization

Result: Buttery-smooth 60fps animations with zero JavaScript.

🌐 Browser Support

• ✅ All modern browsers (Chrome, Firefox, Safari, Edge)
• ✅ CSS Custom Properties required
• ✅ CSS Transforms required

📄 License

This project is licensed under the MIT License.