outline: deep#

Surge Plugin#

The surge plugin powers enter/leave transitions for conditional DOM. It combines CSS property interpolation, optional View Transitions, and a signal-aware state machine to animate elements appearing or disappearing.

Quick Start#

<section data-volt-surge="isOpen:fade">
  <p>Panel content...</p>
</section>

• isOpen resolves to a signal. Falsy values hide the element (display: none).
• The fade preset runs when the signal flips to truthy and again in reverse when it returns to falsy.

Presets and Overrides#

data-volt-surge="presetName" attaches a preset from the transition registry without watching a signal. Combine with granular variants when you need independent enter/leave control:

<article
  data-volt-surge="show:slide-down.400"
  data-volt-surge:enter="fade.200"
  data-volt-surge:leave="scale-down.250">
  ...
</article>

• data-volt-surge:enter and :leave use the same parsing logic as the core transition helpers (duration.delay suffixes honored via parseTransitionValue and applyOverrides).
• When both shorthand and phase-specific attributes exist, the phase-specific value wins.

Signal Lifecycle#

When bound to a signal the plugin:

1. Checks the initial signal value. Falsy values hide the element immediately.
2. Subscribes to the signal and debounces concurrent transitions so rapid toggles stay smooth.
3. Uses execEnter/execLeave helpers to apply styles, classes, delays, and easing.
4. Cleans up the subscription when the element unmounts.

The underlying transition promise resolves before the element is marked visible or hidden, ensuring sequential updates remain ordered.

View Transitions Integration#

Surge participates in the View Transition API whenever the preset’s config opts in (default). Calling variants like slide-down.400 runs inside withViewTransition, making swapping sections feel native. Add :notransition to your navigate bindings if you need to avoid double animations when combining plugins.

Manual Execution#

Volt’s runtime calls the internal helpers automatically for keyed iterations and DOM diffs. If you render content manually, you can trigger the same behavior:

import { executeSurgeEnter, executeSurgeLeave, hasSurge } from "volt/plugins/surge";

if (hasSurge(el)) {
  await executeSurgeEnter(el);
}

hasSurge checks whether the element owns any surge metadata (signal config or phase overrides) before attempting an explicit enter/leave.

Reduced Motion#

When the user prefers reduced motion the plugin skips transitions, applies the to styles or classes immediately, and avoids firing View Transition effects. This keeps the animation accessible without extra work on your part.