Responsive Animations

When building responsive websites, animations that look great on a wide desktop screen often break or overflow on a small mobile device.

responsive() allows you to scope animations to specific CSS media queries. When the browser window resizes and crosses a breakpoint, AnimX automatically kills the old animations, reverts inline styles, and triggers the new animations.

---

1. Breakpoint Contexts

Create a context using responsive() and add conditions using standard CSS media queries.

WARNING

Click the device icons in the control bar below to shrink it across the 600px and 400px thresholds to see the 3 different layouts trigger dynamically!

Click the device icons in the control bar above to test all 3 breakpoints!

60 FPS

When the screen crosses the 600px boundary, any tweens attached to the old context are instantly stopped, their inline styles are wiped clean, and the new context takes over.

IMPORTANT

You must call context.add(tween) inside your handler. This registers the animation so AnimX knows what to kill when the breakpoint changes. If you forget this, your animations will pile up and conflict with each other!

---

2. Custom Cleanup

Sometimes you need to apply custom logic inside a breakpoint that AnimX can't automatically revert. For example, attaching DOM event listeners for mouse hover effects (which don't exist on mobile).

To clean up custom logic, simply return a cleanup function from your handler.

On desktop, hover the button to see the effect. Click the device icons in the control bar above to switch to mobile and trigger the pulsing animation! Also, check the console to see when event listeners are attached and removed.

60 FPS

When the window resizes below 600px, your returned cleanup function fires, ensuring the hover event listeners are safely removed before the mobile layout takes over.

---

API Reference

responsive()

Creates and returns a new ResponsiveContext instance.

Instance Methods

Method	Description
add(query, handler)	Registers a new responsive breakpoint. The handler executes whenever the query matches.
remove(query)	Unregisters a specific media query and immediately reverts any animations/styles it created.
revert()	Loops through every registered media query, removes them, and reverts all styles. Alias for kill().
kill()	Identical to revert().

The handler Callback

When you call ctx.add(query, handler), your handler function receives a context object as its only argument.

import { animate } from 'animx';

ctx.add('(min-width: 1024px)', (context) => {
  const tween = animate('.box', { x: 200 })
  
  // 1. Register tweens so they revert automatically
  context.add(tween)
  
  // 2. (Optional) Return custom cleanup logic for event listeners
  return () => {
    // Custom cleanup code runs when the breakpoint stops matching
  }
})

Context Methods

Method	Description
context.add(tween)	Registers an AnimX tween or timeline with this breakpoint. When the breakpoint no longer matches, AnimX will automatically call kill() on the tween and revert its inline styles.
context.revert()	Manually triggers the cleanup process for this specific breakpoint (kills its tweens and runs the returned cleanup function).