Performance

overwrite

overwrite is a GSAP tween property that decides what happens when a new tween targets a property another tween is already animating. Set it to `"auto"` and GSAP kills only the conflicting parts of other active tweens on the same target, so the new tween takes over cleanly instead of two tweens fighting over the same value frame by frame.

Updated June 30, 2026

Mechanics

How overwrite works

When two tweens animate the same property of the same element at the same time, GSAP has to decide who wins. By default it lets both run, and they fight: each one writes its own value every frame and the element jitters or snaps to whichever rendered last. overwrite is the property that resolves that conflict.

script.js

It takes one of three values, and the gap between them matters in practice:

  • false (the default): both tweens keep running. They compete on every frame, which is where the snapping and jitter come from.
  • true: the new tween immediately kills every other active tween of the same target, including properties that don't overlap.
  • "auto": when the new tween first renders, it kills only the individual overlapping properties in other active tweens of the same target. The non-conflicting tweens keep going.

Why this is a performance entry

Two tweens writing to the same transform every frame is one way an animation drops frames. For context, non-composited (the jank-prone) animations run on about 40% of mobile and 44% of desktop pages (Web Almanac 2025). overwrite: "auto" doesn't make a tween composited, but it stops you paying for two tweens when you only meant to run one.
When

Reach for overwrite: "auto" when

  • Hover-in and hover-out tweens target the same property (a button pulls toward the cursor on mouseenter, springs back on mouseleave, both animating x/y)
  • A panel or drawer can be re-toggled before its open/close tween has finished
  • A click handler can fire faster than the tween it starts (rapid taps on the same element)
  • Any event-driven gsap.to on a property a previous tween of the same element might still be animating
Alternatives

Use something else when

  • You want a hard reset that kills ALL tweens of the target, overlapping or not, use overwrite: true
  • The events fire at mousemove or scroll rate, use gsap.quickTo instead. It reuses one tween and updates its end value, so no second tween is ever spawned and there's nothing to overwrite
  • Open and close are true mirrors of each other, build one reversible timeline and call play() / reverse(). There are no competing tweens to resolve
  • The tweens animate genuinely different properties (one does x, another does opacity) and should run together, leave it on the false default
In production

Used in these Annnimate components

Both of these run on real cursor-driven work where a new tween fires while the last one is still going:

  • The Custom Cursor sets overwrite: true on its follow tween, so every new position tween kills the previous one and the cursor never lags behind a stack of stale tweens as the mouse moves
  • The Magnetic Button runs the magnetic pull on mousemove and the spring-back on mouseleave, both on the same x/y. When the cursor leaves mid-pull, the release tween and the pull tween are competing for the same property, which is exactly the conflict overwrite exists to settle

Watch the global default

You can set gsap.defaults({ overwrite: "auto" }) to apply it everywhere, but be deliberate about it. Once it's global, a tween that was intentionally meant to layer on top of another (different properties, same element) can silently get killed. Prefer setting overwrite per tween where the conflict actually is.
Used in components

See it running in production

Magnetic ButtonThe button and its text gently pull toward your cursor and drift with it, so it feels like it's reaching for you.Custom CursorA custom cursor that follows your mouse smoothly and can show a little label when you hover things.
FAQ

Common questions

What's the difference between overwrite: true and overwrite: "auto"?
true kills every other active tween of the same target the moment the new tween starts, even tweens animating properties that don't overlap. "auto" only kills the specific overlapping properties, and it does it when the new tween first renders rather than at creation. "auto" is the safer pick most of the time because it leaves unrelated tweens alone. Use true when you genuinely want a clean slate on that element.
Why does my hover animation snap or jitter when I move the mouse fast?
Almost always two tweens fighting over the same property with the default overwrite: false. The enter tween hasn't finished when the leave tween starts, so both write x/y every frame and the element snaps between their values. Add overwrite: "auto" to the tweens, or for mousemove-rate updates switch to gsap.quickTo so there's only ever one tween.
Does overwrite kill the whole timeline or just the tween?
It works on individual tweens of the same target, not timelines. A tween with overwrite: "auto" kills the conflicting parts of other active TWEENS on that element. It won't reach into a timeline and stop it. If you need to stop a timeline, control the timeline directly with pause() / kill().
Should I set overwrite globally with gsap.defaults?
You can, with gsap.defaults({ overwrite: "auto" }), and some teams do. The risk is that a tween you meant to layer on top of another one (animating a different property on the same element) can get killed once the default is on. It's usually cleaner to set overwrite per tween at the spot where the conflict actually happens, so the behavior is visible in the code that needs it.
overwrite vs killTweensOf, which should I use?
overwrite is automatic and lives on the new tween, GSAP resolves the conflict for you as that tween starts. gsap.killTweensOf(target) is manual and imperative, you call it yourself before starting the next tween. Use overwrite for the common event-driven case (hover, click, drag). Reach for killTweensOf when you need to clear tweens at a moment that isn't tied to starting a new one, like on cleanup or a state reset.
Previousforce3Dforce3D is the GSAP property that forces an animated element onto its own GPU layer by applying a 3D transform matrix even when the animation is 2D-only.Nextwill-changewill-change is a CSS property that hints to the browser which properties are about to animate, letting it pre-promote the element to its own GPU layer.
Related conceptsgsap.quickTo()autoAlphawill-change