or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-plugins.mdanimation-control.mdcore-animation.mdcss-properties.mddraggable.mdindex.mdscroll-trigger.mdsvg-animation.mdtext-animation.mdtimeline-system.mdutility-functions.md
tile.json

css-properties.mddocs/

CSS Properties

GSAP's CSSPlugin enables animation of virtually all CSS properties with optimized performance and cross-browser compatibility. It provides special transform properties, shortcuts, and handles vendor prefixes automatically.

Setup

The CSS plugin is automatically registered with the main GSAP import:

import gsap from "gsap"; // CSSPlugin is included by default

Capabilities

Transform Properties

Optimized 2D and 3D transform properties with hardware acceleration.

interface TransformProperties {
  // Translation
  x?: number | string;           // translateX (pixels or other units)
  y?: number | string;           // translateY
  z?: number | string;           // translateZ (for 3D)
  
  // Alternative translation syntax
  translateX?: number | string;  // Same as x
  translateY?: number | string;  // Same as y
  translateZ?: number | string;  // Same as z
  
  // Rotation
  rotation?: number | string;    // 2D rotation in degrees
  rotationX?: number | string;   // 3D rotation around X axis
  rotationY?: number | string;   // 3D rotation around Y axis
  rotationZ?: number | string;   // 3D rotation around Z axis (same as rotation)
  
  // Alternative rotation syntax
  rotate?: number | string;      // Same as rotation
  rotateX?: number | string;     // Same as rotationX
  rotateY?: number | string;     // Same as rotationY
  rotateZ?: number | string;     // Same as rotationZ
  
  // Scale
  scale?: number | string;       // Uniform scale
  scaleX?: number | string;      // Scale X axis only
  scaleY?: number | string;      // Scale Y axis only
  scaleZ?: number | string;      // Scale Z axis only (3D)
  
  // Skew
  skew?: number | string;        // Skew both axes
  skewX?: number | string;       // Skew X axis only
  skewY?: number | string;       // Skew Y axis only
  
  // Transform origin
  transformOrigin?: string;      // Transform origin point ("50% 50%", "top left", etc.)
  transformPerspective?: number; // 3D perspective
}

Usage Examples:

// Basic transforms
gsap.to(".box", {
  duration: 2,
  x: 100,           // Move 100px right
  y: 50,            // Move 50px down
  rotation: 45,     // Rotate 45 degrees
  scale: 1.5        // Scale to 150%
});

// 3D transforms
gsap.to(".card", {
  duration: 1,
  rotationY: 180,   // Flip around Y axis
  z: 100,           // Move forward in 3D space
  transformPerspective: 1000
});

// Complex transform sequence
gsap.timeline()
  .to(".element", { rotation: 360, duration: 2 })
  .to(".element", { scaleX: 2, scaleY: 0.5, duration: 1 })
  .to(".element", { skewX: 30, duration: 1 });

Special Properties

GSAP-specific properties that provide convenient shortcuts and enhanced functionality.

interface SpecialProperties {
  // Opacity shortcuts
  autoAlpha?: number;           // Opacity + visibility combined (0 sets visibility:hidden)
  alpha?: number;               // Alias for opacity
  
  // Percentage-based positioning
  xPercent?: number;            // X position as percentage of element width
  yPercent?: number;            // Y position as percentage of element height
  
  // Transform origin
  svgOrigin?: string;           // SVG-specific transform origin
  smoothOrigin?: boolean;       // Smooth transform origin changes
  
  // Special behaviors
  force3D?: boolean | "auto";   // Force 3D rendering for performance
  throwProps?: object;          // For momentum-based animations
}

Usage Examples:

// AutoAlpha for fade in/out with visibility
gsap.fromTo(".modal", 
  { autoAlpha: 0 },     // opacity: 0, visibility: hidden
  { autoAlpha: 1, duration: 0.5 }  // opacity: 1, visibility: visible
);

// Percentage-based positioning
gsap.to(".centered-element", {
  xPercent: -50,        // Move left by 50% of element width
  yPercent: -50,        // Move up by 50% of element height
  left: "50%",          // Position at 50% of container
  top: "50%"            // Perfect centering
});

// SVG transform origin
gsap.to(".svg-element", {
  rotation: 180,
  svgOrigin: "50 50",   // Center point in SVG coordinate system
  duration: 1
});

Standard CSS Properties

GSAP can animate virtually all CSS properties with automatic type detection and conversion.

interface CSSProperties {
  // Layout
  width?: number | string;
  height?: number | string;
  top?: number | string;
  left?: number | string;
  right?: number | string;
  bottom?: number | string;
  margin?: string;
  marginTop?: number | string;
  marginRight?: number | string;
  marginBottom?: number | string;
  marginLeft?: number | string;
  padding?: string;
  paddingTop?: number | string;
  paddingRight?: number | string;
  paddingBottom?: number | string;
  paddingLeft?: number | string;
  
  // Visual
  opacity?: number;
  backgroundColor?: string;
  color?: string;
  borderColor?: string;
  borderWidth?: number | string;
  borderRadius?: number | string;
  boxShadow?: string;
  textShadow?: string;
  
  // Typography
  fontSize?: number | string;
  fontWeight?: number | string;
  lineHeight?: number | string;
  letterSpacing?: number | string;
  
  // Flexbox
  flexBasis?: string;
  flexGrow?: number;
  flexShrink?: number;
  justifyContent?: string;
  alignItems?: string;
  
  // Grid
  gridTemplateColumns?: string;
  gridTemplateRows?: string;
  gridGap?: string;
  
  // Filters
  filter?: string;
  backdropFilter?: string;
  
  // And many more...
  [property: string]: any;  // Any CSS property
}

Usage Examples:

// Layout animation
gsap.to(".sidebar", {
  duration: 0.5,
  width: "300px",
  height: "100vh",
  backgroundColor: "#333"
});

// Color animations
gsap.to(".button", {
  duration: 0.3,
  backgroundColor: "#ff6b6b",
  color: "#ffffff",
  borderColor: "#ff5252"
});

// Typography animation
gsap.to(".title", {
  duration: 1,
  fontSize: "3em",
  fontWeight: 700,
  letterSpacing: "0.1em"
});

// Filter effects
gsap.to(".image", {
  duration: 1,
  filter: "blur(5px) brightness(1.2) contrast(1.1)"
});

Shorthand Properties

GSAP supports CSS shorthand properties and intelligently handles sub-properties.

interface ShorthandProperties {
  // Border shorthand
  border?: string;              // "2px solid red"
  borderTop?: string;
  borderRight?: string;
  borderBottom?: string;
  borderLeft?: string;
  
  // Background shorthand
  background?: string;          // "url(image.jpg) center/cover"
  
  // Font shorthand
  font?: string;               // "bold 16px/1.5 Arial"
  
  // Margin/padding shorthand
  margin?: string;             // "10px 20px"
  padding?: string;            // "5px 10px 15px 20px"
  
  // Transform shorthand (auto-converted)
  transform?: string;          // "translateX(100px) rotate(45deg)"
}

Usage Examples:

// Shorthand properties
gsap.to(".element", {
  duration: 1,
  border: "3px solid blue",
  margin: "20px auto",
  background: "linear-gradient(45deg, red, blue)"
});

// Mixed shorthand and individual properties
gsap.to(".box", {
  duration: 2,
  padding: "20px",
  paddingTop: "40px",      // Overrides top padding from shorthand
  border: "1px solid #ccc",
  borderRadius: "10px"
});

CSS Variables (Custom Properties)

Animate CSS custom properties (CSS variables) for dynamic theming and design systems.

interface CSSVariables {
  [key: `--${string}`]: string | number;  // CSS variables with -- prefix
}

Usage Examples:

// Animate CSS variables
gsap.to(":root", {
  duration: 2,
  "--primary-color": "#ff6b6b",
  "--font-size": "18px",
  "--spacing": "2rem"
});

// Element-specific CSS variables
gsap.to(".theme-section", {
  duration: 1,
  "--section-bg": "#f0f0f0",
  "--text-color": "#333",
  "--border-radius": "15px"
});

Relative Values

Use relative value syntax for dynamic animations based on current values.

// Relative value syntax
type RelativeValue = string; // Examples:
// "+=100"  - Add 100 to current value
// "-=50"   - Subtract 50 from current value
// "*=2"    - Multiply current value by 2
// "/=2"    - Divide current value by 2

Usage Examples:

// Relative transforms
gsap.to(".box", {
  duration: 1,
  x: "+=100",         // Move 100px right from current position
  rotation: "+=180",   // Rotate 180 degrees from current rotation
  scale: "*=1.5"      // Scale to 1.5x current scale
});

// Relative CSS properties
gsap.to(".element", {
  duration: 0.5,
  width: "+=50px",    // Increase width by 50px
  fontSize: "*=1.2",  // Increase font size by 20%
  opacity: "-=0.3"    // Reduce opacity by 0.3
});

Units and Conversions

GSAP automatically handles unit conversion between different CSS units.

interface UnitConversion {
  // Supported units for numeric properties
  px: number;    // Pixels
  "%": number;   // Percentage
  em: number;    // Em units
  rem: number;   // Rem units
  vh: number;    // Viewport height
  vw: number;    // Viewport width
  vmin: number;  // Viewport minimum
  vmax: number;  // Viewport maximum
  pt: number;    // Points
  pc: number;    // Picas
  in: number;    // Inches
  cm: number;    // Centimeters
  mm: number;    // Millimeters
}

Usage Examples:

// Mixed units in same animation
gsap.to(".responsive-element", {
  duration: 1,
  width: "50vw",      // 50% of viewport width
  height: "300px",    // Fixed pixel height
  fontSize: "2rem",   // Relative to root font size
  margin: "5%"        // Percentage of container
});

// Unit conversion (GSAP handles automatically)
gsap.fromTo(".element",
  { width: "100px" },    // Starting in pixels
  { width: "50%", duration: 1 }  // Ending in percentage
);

Performance Considerations

Best practices for optimal CSS animation performance.

interface PerformanceProperties {
  // Hardware-accelerated properties (prefer these)
  x: number;              // Instead of left
  y: number;              // Instead of top
  scale: number;          // Instead of width/height when possible
  rotation: number;       // Instead of transform: rotate()
  opacity: number;        // Always hardware accelerated
  
  // 3D acceleration
  force3D?: boolean;      // Force 3D rendering context
  z?: number;            // Minimal z-translate for 3D context
}

Usage Examples:

// Optimized for performance
gsap.to(".fast-element", {
  duration: 1,
  x: 100,           // Hardware accelerated
  y: 50,            // Hardware accelerated
  scale: 1.2,       // Hardware accelerated
  opacity: 0.8,     // Hardware accelerated
  force3D: true     // Ensure 3D context
});

// Less optimal (but sometimes necessary)
gsap.to(".layout-element", {
  duration: 1,
  left: "100px",    // Triggers layout recalculation
  top: "50px",      // Triggers layout recalculation
  width: "200px",   // Triggers layout recalculation
  height: "150px"   // Triggers layout recalculation
});