Does gsap.getProperty return a number or a string?

For numeric properties (transforms like x/y/rotation/scale, opacity, and pixel lengths) it returns a plain number with the unit stripped, so you can do math on it right away. For values that are inherently strings, like a color, it returns the string (e.g. 'rgb(20, 20, 20)'). If you need a specific unit back, pass it as the third argument.

How do I get a value in a specific unit like % or rem?

Pass the unit as the third argument: gsap.getProperty(el, 'width', '%') returns the width as a percentage of its parent, gsap.getProperty(el, 'x', 'rem') returns the translate in rem. GSAP does the conversion against the element's actual context, which is the main thing getComputedStyle won't do for you.

What's the difference between gsap.getProperty and getComputedStyle?

getComputedStyle returns CSS strings ('320px', 'matrix(1,0,0,1,40,0)') that you have to parse and decompose yourself. gsap.getProperty returns a ready-to-use number, reads GSAP's cached transform value (so x is 40, not a matrix), and converts units on request. Use getComputedStyle when you need a value the CSS cascade owns and GSAP has never animated.

Can I read a value while a tween is running?

Yes. getProperty reads the element's current state, so calling it inside an onUpdate callback or a requestAnimationFrame loop returns the live animated value each time. If you only need the tween's own eased progress, reading this.progress() or this.ratio off the tween is cheaper than re-querying the element.

Does gsap.getProperty work with a selector string?

Yes, you can pass a selector string like '.box' and it reads the first matching element. Passing the element reference directly is slightly faster since it skips the DOM lookup, and if you're reading several properties off the same node, omit the property name to get a reusable getter function bound to that element.

Core

gsap.getProperty()

gsap.getProperty is a GSAP core method that reads an element's current value for a given property, returning a real number instead of a CSS string so you can do math with it directly. It reads GSAP's own transform cache, so `gsap.getProperty(el, "x")` gives you the logical translate value mid-tween, not a decomposed matrix you have to parse yourself.

Updated July 1, 2026

Mechanics

How gsap.getProperty works

You pass a target and a property name, and it returns the current value. For anything numeric (transforms, opacity, pixel lengths) you get back a plain number with the unit stripped, so it drops straight into a calculation. For values that are inherently strings (like a color) you get the string back.

script.js

Pass a third argument to convert the value into a specific unit. This is the part getComputedStyle won't do for you, GSAP does the px-to-percent (or rem, em, vw) conversion against the element's context.

script.js

If you omit the property name, you get back a reusable getter function bound to that one element. Handy when you're reading several properties off the same node in a loop or a tick handler, it skips re-resolving the target each time.

script.js

It reads the transform cache

For x, y, rotation, scale, skewX and the other transform aliases, getProperty returns GSAP's cached logical value, not a raw matrix() you'd have to decompose. That's why reading x mid-tween gives you 40, not a six-number matrix string.

When

Use gsap.getProperty for

Reading an element's current animated x/y/rotation to compute the next tween from it (drag release, spring-back, momentum)
Getting a numeric value with the unit stripped so you can feed it into gsap.utils.mapRange, clamp, or plain arithmetic
Converting a length between units on the fly, getProperty(el, "width", "%") instead of doing the px math by hand
Snapshotting a start value inside an onUpdate or a requestAnimationFrame loop without re-parsing computed styles every frame

Alternatives

Use something else when

You need the element's live layout box on screen (position, size after scroll/transform) - use getBoundingClientRect(), getProperty reads the logical transform, not the painted rect
You want a value the CSS cascade is driving and GSAP has never touched - getComputedStyle(el).getPropertyValue(...) is the source of truth there
You're inside a tween's onUpdate and just want the tween's own progress or eased value - read this.progress() / this.ratio off the tween instead of re-querying the DOM
You want to WRITE a value, not read one - that's gsap.set (or a tween), getProperty is read-only

In production

Used in these Annnimate components

getProperty is the read side of any pointer-driven component: before you tween an element toward a target, you often need where it currently is. Two Annnimate components live in exactly that read-then-tween loop:

The Magnetic Button computes its pull from the cursor's position inside the button and springs the label back to rest. When you need the label's current animated offset mid-spring rather than its layout box, gsap.getProperty(el, "x") is the read that returns it as a number.
The Custom Cursor follows the pointer and reacts on hover. getProperty is the GSAP-native way to sample the cursor's current x/y or scale between frames without re-parsing computed styles.

GSAP runs on roughly 2.2% of all websites (w3techs, June 2026), and every one of those installs already ships getProperty as part of the core, there's no extra plugin to register. If GSAP is already on the page, reach for getProperty before hand-parsing getComputedStyle, it hands back a number and does unit conversion the computed-style API won't. Reference: the GSAP core docs at gsap.com/docs/v3/GSAP/gsap.getProperty().

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

Does gsap.getProperty return a number or a string?: For numeric properties (transforms like x/y/rotation/scale, opacity, and pixel lengths) it returns a plain number with the unit stripped, so you can do math on it right away. For values that are inherently strings, like a color, it returns the string (e.g. 'rgb(20, 20, 20)'). If you need a specific unit back, pass it as the third argument.
How do I get a value in a specific unit like % or rem?: Pass the unit as the third argument: gsap.getProperty(el, 'width', '%') returns the width as a percentage of its parent, gsap.getProperty(el, 'x', 'rem') returns the translate in rem. GSAP does the conversion against the element's actual context, which is the main thing getComputedStyle won't do for you.
What's the difference between gsap.getProperty and getComputedStyle?: getComputedStyle returns CSS strings ('320px', 'matrix(1,0,0,1,40,0)') that you have to parse and decompose yourself. gsap.getProperty returns a ready-to-use number, reads GSAP's cached transform value (so x is 40, not a matrix), and converts units on request. Use getComputedStyle when you need a value the CSS cascade owns and GSAP has never animated.
Can I read a value while a tween is running?: Yes. getProperty reads the element's current state, so calling it inside an onUpdate callback or a requestAnimationFrame loop returns the live animated value each time. If you only need the tween's own eased progress, reading this.progress() or this.ratio off the tween is cheaper than re-querying the element.
Does gsap.getProperty work with a selector string?: Yes, you can pass a selector string like '.box' and it reads the first matching element. Passing the element reference directly is slightly faster since it skips the DOM lookup, and if you're reading several properties off the same node, omit the property name to get a reusable getter function bound to that element.

Previousgsap.delayedCall()gsap.delayedCall is a GSAP core method that runs a function once after a set number of seconds, like setTimeout, but on GSAP's own clock instead of the browser's.Nextgsap.registerEffect()gsap.registerEffect is a GSAP core method that packages an animation into a named, reusable recipe you call as gsap.effects.name(targets, config).