tessl/npm-gsap

High-performance JavaScript animation library for animating CSS, SVG, canvas, React, Vue, WebGL, and any JavaScript-accessible properties.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

CSS Properties

Name: tessl/npm-gsap
Author: tessl

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
});