Animations & Transitions

VoltX provides a powerful, declarative animation system through two complementary plugins:

1. surge for enter/leave transitions and
2. shift for CSS keyframe animations.

Both integrate with the reactivity system and respect user accessibility preferences.

Quick Start

Add transitions to any element with data-volt-if or data-volt-show by adding data-volt-surge with a preset name:

<div data-volt-if="isVisible" data-volt-surge="fade">
  Content fades in and out smoothly
</div>

That's it! The surge plugin automatically hooks into the element's lifecycle, applying transitions when it appears or disappears.

Built-in Presets

VoltX includes ready-to-use transition presets:

Preset	Description
fade	Simple opacity transition
slide-up	Sliding motion with opacity
slide-down
slide-left
slide-right
scale	Subtle scale effect with opacity
blur	Blur effect combined with opacity

All presets are designed with smooth, professional timing curves and 300ms duration by default.

Surge Plugin: Enter/Leave Transitions

The surge plugin provides two modes of operation: automatic (with if/show bindings) and explicit (signal-based).

Automatic Mode

When used with data-volt-if or data-volt-show, surge automatically manages the element's visibility transitions. The element smoothly animates in when the condition becomes true and animates out before removal.

Explicit Mode

Watch any signal by providing a signal path. The element will transition in/out based on the signal's truthiness:

<div data-volt-surge="showPanel:slide-down">
  Panel slides down when showPanel is true
</div>

Duration and Delay Modifiers

Override preset timing using dot notation:

<!-- 500ms duration -->
<div data-volt-surge="fade.500">...</div>

<!-- 600ms duration, 100ms delay -->
<div data-volt-surge="slide-down.600.100">...</div>

Granular Control

Specify different transitions for enter and leave phases:

<div
  data-volt-if="show"
  data-volt-surge:enter="slide-down.400"
  data-volt-surge:leave="fade.200">
  Slides in, fades out
</div>

Shift Plugin: Keyframe Animations

The shift plugin applies CSS keyframe animations, perfect for attention-grabbing effects and continuous animations.

Built-in Animations

Animation	Description
bounce	Quick bounce effect
shake	Horizontal shake motion
pulse	Subtle pulsing scale (continuous)
spin	Full rotation (continuous)
flash	Opacity flash effect

One-Time Animations

Apply animation when element mounts:

<button data-volt-shift="bounce">Bounces on mount</button>

Signal-Triggered Animations

Trigger animations based on signal changes:

<div data-volt-shift="error:shake.600.2">
  Shakes twice when error becomes truthy
</div>

The syntax supports duration and iteration overrides: animationName.duration.iterations

View Transitions API

VoltX automatically uses the View Transitions API when available, providing native browser-level transitions for ultra-smooth visual updates. The system gracefully falls back to CSS transitions on unsupported browsers.

For advanced use cases, manually trigger view transitions using startViewTransition or namedViewTransition from the programmatic API.

Custom Presets (Programmatic Mode)

Register custom transitions for reuse across your application:

import { registerTransition } from "voltx.js";

registerTransition("custom-slide", {
  enter: {
    from: { opacity: 0, transform: "translateX(-100px)" },
    to: { opacity: 1, transform: "translateX(0)" },
    duration: 400,
    easing: "cubic-bezier(0.4, 0, 0.2, 1)",
  },
  leave: {
    from: { opacity: 1, transform: "translateX(0)" },
    to: { opacity: 0, transform: "translateX(100px)" },
    duration: 300,
    easing: "ease-out",
  },
});

Similarly, register custom shift animations with registerAnimation.

Easing Functions

Surge supports standard CSS easing values plus extended named easings:

• Standard: linear, ease, ease-in, ease-out, ease-in-out
• Extended: ease-in-sine, ease-out-quad, ease-in-out-cubic, ease-in-back

Custom cubic-bezier values are also supported.

Integration with Bindings

• With data-volt-if, surge defers element insertion/removal until transitions complete, preventing visual glitches.
• With data-volt-show, surge manages display property changes around the transition lifecycle.
• Simply add data-volt-surge to elements already using these bindings.

Accessibility

The animation system automatically respects the prefers-reduced-motion media query. When enabled, animations are skipped or significantly reduced, instantly applying final states instead.

Both surge and shift plugins honor this setting by default, ensuring your application remains accessible without additional configuration.