a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
desertthunder.dev
hypermedia
frontend
signals
1# Animations & Transitions
2
3VoltX provides a powerful, declarative animation system through two complementary plugins:
4
51. **surge** for enter/leave transitions and
62. **shift** for CSS keyframe animations.
7
8Both integrate with the reactivity system and respect user accessibility preferences.
9
10## Quick Start
11
12Add transitions to any element with `data-volt-if` or `data-volt-show` by adding `data-volt-surge` with a preset name:
13
14```html
15<div data-volt-if="isVisible" data-volt-surge="fade">
16 Content fades in and out smoothly
17</div>
18```
19
20That's it! The surge plugin automatically hooks into the element's lifecycle, applying transitions when it appears or disappears.
21
22## Built-in Presets
23
24VoltX includes ready-to-use transition presets:
25
26| Preset | Description |
27| --------------- | --------------------------------- |
28| **fade** | Simple opacity transition |
29| **slide-up** | Sliding motion with opacity |
30| **slide-down** | |
31| **slide-left** | |
32| **slide-right** | |
33| **scale** | Subtle scale effect with opacity |
34| **blur** | Blur effect combined with opacity |
35
36All presets are designed with smooth, professional timing curves and 300ms duration by default.
37
38## Surge Plugin: Enter/Leave Transitions
39
40The surge plugin provides two modes of operation: automatic (with if/show bindings) and explicit (signal-based).
41
42### Automatic Mode
43
44When 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.
45
46### Explicit Mode
47
48Watch any signal by providing a signal path. The element will transition in/out based on the signal's truthiness:
49
50```html
51<div data-volt-surge="showPanel:slide-down">
52 Panel slides down when showPanel is true
53</div>
54```
55
56### Duration and Delay Modifiers
57
58Override preset timing using dot notation:
59
60```html
61<!-- 500ms duration -->
62<div data-volt-surge="fade.500">...</div>
63
64<!-- 600ms duration, 100ms delay -->
65<div data-volt-surge="slide-down.600.100">...</div>
66```
67
68### Granular Control
69
70Specify different transitions for enter and leave phases:
71
72```html
73<div
74 data-volt-if="show"
75 data-volt-surge:enter="slide-down.400"
76 data-volt-surge:leave="fade.200">
77 Slides in, fades out
78</div>
79```
80
81## Shift Plugin: Keyframe Animations
82
83The shift plugin applies CSS keyframe animations, perfect for attention-grabbing effects and continuous animations.
84
85### Built-in Animations
86
87| Animation | Description |
88| ---------- | --------------------------------- |
89| **bounce** | Quick bounce effect |
90| **shake** | Horizontal shake motion |
91| **pulse** | Subtle pulsing scale (continuous) |
92| **spin** | Full rotation (continuous) |
93| **flash** | Opacity flash effect |
94
95### One-Time Animations
96
97Apply animation when element mounts:
98
99```html
100<button data-volt-shift="bounce">Bounces on mount</button>
101```
102
103### Signal-Triggered Animations
104
105Trigger animations based on signal changes:
106
107```html
108<div data-volt-shift="error:shake.600.2">
109 Shakes twice when error becomes truthy
110</div>
111```
112
113The syntax supports duration and iteration overrides: `animationName.duration.iterations`
114
115## View Transitions API
116
117VoltX automatically uses the View Transitions API when available, providing native browser-level transitions for ultra-smooth visual updates.
118The system gracefully falls back to CSS transitions on unsupported browsers.
119
120For advanced use cases, manually trigger view transitions using `startViewTransition` or `namedViewTransition` from the programmatic API.
121
122## Custom Presets (Programmatic Mode)
123
124Register custom transitions for reuse across your application:
125
126```javascript
127import { registerTransition } from "voltx.js";
128
129registerTransition("custom-slide", {
130 enter: {
131 from: { opacity: 0, transform: "translateX(-100px)" },
132 to: { opacity: 1, transform: "translateX(0)" },
133 duration: 400,
134 easing: "cubic-bezier(0.4, 0, 0.2, 1)",
135 },
136 leave: {
137 from: { opacity: 1, transform: "translateX(0)" },
138 to: { opacity: 0, transform: "translateX(100px)" },
139 duration: 300,
140 easing: "ease-out",
141 },
142});
143```
144
145Similarly, register custom shift animations with `registerAnimation`.
146
147## Easing Functions
148
149Surge supports standard CSS easing values plus extended named easings:
150
151- Standard: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`
152- Extended: `ease-in-sine`, `ease-out-quad`, `ease-in-out-cubic`, `ease-in-back`
153
154Custom cubic-bezier values are also supported.
155
156## Integration with Bindings
157
158- With `data-volt-if`, surge defers element insertion/removal until transitions complete, preventing visual glitches.
159- With `data-volt-show`, surge manages display property changes around the transition lifecycle.
160- Simply add `data-volt-surge` to elements already using these bindings.
161
162## Accessibility
163
164The animation system automatically respects the `prefers-reduced-motion` media query. When enabled, animations are skipped or significantly reduced, instantly applying final states instead.
165
166Both surge and shift plugins honor this setting by default, ensuring your application remains accessible without additional configuration.