Diagnose motion quickly
Troubleshooting
Fix missing animations, undefined sets, transform conflicts, clipping, blank space, flashes, and dynamic-content issues.
FIX
| Problem | Likely Cause | Fix |
|---|---|---|
| Nothing animates | JS did not load or selectors are missing | Confirm hf-motion.min.js loads and the element has a valid data-hf value. |
| Preset has no effect | Set file loaded after library or set name is undefined | Load hf-motion-sets.js first and verify type + set name. |
| Fade/parallax fight each other | Both effects are on the same element | Move one effect to a wrapper. |
| Hover transform stops working | HF Motion owns transform on that element | Apply HF Motion to an outer wrapper and hover transform to an inner component. |
| Parallax looks clipped | Ancestor uses overflow: hidden | Remove clipping or intentionally enlarge the clipping region. |
| Parallax exposes blank space | Distance/speed is too strong for the layout | Reduce values or provide extra image bleed. |
| Reveal flashes before JS | The runtime was deferred or delayed without the head bootstrap | Run the inline first-paint bootstrap in the head and use data-hf-trigger="load" on opening-viewport reveals. |
| Dynamic content does not animate | Mutation observer disabled or content added unusually | Enable observeMutations or call HFMotion.refresh(scope). |
| Animation replays unexpectedly | data-hf-once is false | Remove the attribute or set it to true. |
| RTL direction feels wrong | Physical left/right used instead of logical start/end | Use start/end for language-aware layouts. |
Browser Fallbacks
If CSS custom properties are unsupported, HF Motion removes its ready flag so content remains visible.
If IntersectionObserver is unavailable, reveal effects are shown instead of remaining hidden.
If the runtime does not initialize within three seconds, the first-paint bootstrap removes its guard so load-triggered content cannot remain hidden.
If prefers-reduced-motion is enabled, reveals are shown and parallax offsets reset.