htmx-transition-manager

v1.0.0

Published

19 days ago

Declarative CSS transitions for HTMX content swapping - single file, zero dependencies

0High
0Medium
0Low

iqbalarain

htmx extension transitions animations css swap declarative hypermedia single-file zero-dependencies

HTMX Transition Manager

A lightweight HTMX extension that provides declarative, smooth CSS animations for content swapping and removal.

Features

🎨 10+ Built-in Animations - fade, slide, scale, flip, zoom, collapse, and bounce
⚡ Single File - No separate CSS file needed! (~13KB unminified, ~8KB minified)
🎯 Declarative API - Control transitions with simple HTML attributes
🔄 Smart Timing - Waits for exit animations before swapping content
📦 Zero Dependencies - Just HTMX, nothing else
🎭 Flexible - Easy to add custom animations

Installation

CDN (Recommended - Single File!)

<!-- HTMX -->
<script src="https://unpkg.com/[email protected]"></script>

<!-- Transition Manager - Single file with CSS included! -->
<script src="https://unpkg.com/htmx-transition-manager"></script>

Or use the minified version (8KB):

<script src="https://unpkg.com/htmx-transition-manager/htmx-transition-manager.min.js"></script>

NPM

npm install htmx-transition-manager

Then in your JavaScript:

import 'htmx-transition-manager';

Manual

Download htmx-transition-manager.min.js from the releases page:

<script src="path/to/htmx-transition-manager.min.js"></script>

No separate CSS file needed! Styles are automatically injected.

Quick Start

Enable the extension on your <body> or specific elements:

<body hx-ext="transition-manager">

Add transition attributes to your HTMX elements:

<button 
  hx-get="/content"
  hx-target="#result"
  transition-out="fade"
  transition-in="slideDown"
  transition-duration="300ms">
  Load Content
</button>

<div id="result"></div>

Usage

Basic Example

<div hx-get="/data" 
     hx-swap="innerHTML"
     transition-out="fade" 
     transition-in="slideUp">
  Old content fades out, new content slides up
</div>

Delete with Animation

<button 
  hx-delete="/item/123"
  hx-target="closest .item"
  hx-swap="outerHTML"
  transition-out="slideLeft"
  transition-duration="250ms">
  Delete
</button>

Different In/Out Durations

<div hx-get="/update"
     transition-out="zoom"
     transition-in="bounce"
     transition-out-duration="200ms"
     transition-in-duration="400ms">
  Fast zoom out, slow bounce in
</div>

Attributes

| Attribute | Description | Example | |-----------|-------------|---------| | transition-in | Animation when content enters | fade, slideUp, scale | | transition-out | Animation when content exits | slideLeft, zoom, flip | | transition-duration | Duration for both animations | 300ms, 0.5s | | transition-in-duration | Specific duration for enter | 400ms | | transition-out-duration | Specific duration for exit | 200ms |

Built-in Animations

Fade

transition-out="fade"
transition-in="fade"

Simple opacity transition.

Slide Animations

transition-out="slideUp"    <!-- Slides up and fades -->
transition-out="slideDown"  <!-- Slides down and fades -->
transition-out="slideLeft"  <!-- Slides left and fades -->
transition-out="slideRight" <!-- Slides right and fades -->

Scale Animations

transition-out="scale"      <!-- Subtle scale down -->
transition-out="scaleUp"    <!-- Scale up slightly -->
transition-out="zoom"       <!-- Scale to zero -->

Advanced Animations

transition-out="flip"       <!-- 3D flip effect -->
transition-out="collapse"   <!-- Height-based collapse -->
transition-out="bounce"     <!-- Bouncy scale effect -->

Custom Animations

Add your own animations by defining CSS classes:

/* Define exit animation */
@keyframes my-custom-out {
    from {
        opacity: 1;
        transform: rotate(0deg);
    }
    to {
        opacity: 0;
        transform: rotate(180deg);
    }
}

.htmx-transition-out.htmx-transition-myCustom {
    animation-name: my-custom-out;
}

/* Define enter animation */
@keyframes my-custom-in {
    from {
        opacity: 0;
        transform: rotate(-180deg);
    }
    to {
        opacity: 1;
        transform: rotate(0deg);
    }
}

.htmx-transition-in.htmx-transition-myCustom {
    animation-name: my-custom-in;
}

Then use it:

<div transition-out="myCustom" transition-in="myCustom">
  Content with custom rotation animation
</div>

How It Works

Before Swap: The extension intercepts htmx:beforeSwap event
Exit Animation: Applies CSS animation to elements being removed
Wait: Prevents swap until animation completes
Swap: Executes the HTMX swap operation
Enter Animation: Applies CSS animation to newly added content

Browser Support

Works in all modern browsers that support:

CSS Animations
ES6 Promises
HTMX 1.9+ or 2.0+

Examples

Todo List with Transitions

<div hx-ext="transition-manager">
  <div class="todo-item">
    <input type="checkbox" 
           hx-post="/toggle/1" 
           hx-swap="outerHTML"
           hx-target="closest .todo-item"
           transition-out="fade"
           transition-in="slideDown">
    <span>Buy groceries</span>
    <button 
      hx-delete="/delete/1"
      hx-target="closest .todo-item"
      hx-swap="outerHTML"
      transition-out="slideLeft"
      transition-duration="250ms">
      Delete
    </button>
  </div>
</div>

Loading More Content

<button 
  hx-get="/load-more"
  hx-target="#content"
  hx-swap="beforeend"
  transition-in="slideUp"
  transition-duration="400ms">
  Load More
</button>

<div id="content"></div>

Modal Transitions

<div id="modal" 
     hx-get="/modal-content"
     transition-in="scale"
     transition-out="zoom"
     transition-duration="200ms">
</div>

Configuration

Enable debug logging:

document.addEventListener('DOMContentLoaded', function() {
    // Access the extension instance
    htmx.ext['transition-manager'].debug = true;
});

FAQ

Q: Can I use this with HTMX 1.x?
A: Yes! It's compatible with HTMX 1.9+ and 2.0+.

Q: Does it work with hx-boost?
A: Yes, it works with all HTMX swap operations.

Q: Can I chain multiple animations?
A: Currently supports one in and one out animation. For complex sequences, create custom CSS animations.

Q: What about accessibility?
A: The extension respects prefers-reduced-motion. Add this to your CSS:

@media (prefers-reduced-motion: reduce) {
    .htmx-transition-in,
    .htmx-transition-out {
        animation-duration: 0.01ms !important;
    }
}

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests if applicable
Submit a pull request

License

MIT License - feel free to use in personal and commercial projects.

Credits

Created with ❤️ for the HTMX community.

Inspired by the need for simple, declarative transitions in hypermedia-driven applications.

Changelog

v1.0.0 (Initial Release)

10 built-in animation presets
Declarative attribute-based API
Support for custom animations
Works with all HTMX swap styles
Promise-based animation timing