Chapter 17: gsap.getProperty()

Core Idea

gsap.getProperty() reads the current value of any property on any target — DOM element or plain object — optionally converting it to a specific unit.

Key Concepts

• Lookup order for DOM elements: inline CSS, computed CSS, a property on the element itself, then an attribute — first match wins.
• Number by default: without a unit argument, numeric values come back as plain numbers (e.g. "20px" → 20), which is usually more convenient for animation math than a string.
• Explicit unit: passing a unit (e.g. "px", "em") returns a string with that unit appended/converted.
• Returns null: if the property doesn't exist.

Code Examples

gsap.getProperty("#id", "x"); // 20
gsap.getProperty("#id", "x", "px"); // "20px"
gsap.getProperty(element, "width", "em"); // converted to em

• What it demonstrates: reading the same property as a bare number vs. a unit-suffixed string, and unit conversion on read.

Key Takeaways

1. Prefer this over manually reading getComputedStyle() or element.style — it already handles the fallback chain and unit conversion.
2. Omit the unit argument when you need a number for further math; pass one when you need a display-ready string.

Connects To

• gsap.quickSetter() / gsap.quickTo(): performance-oriented alternatives for setting (not reading) properties repeatedly.