or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

animated-components.mdanimation-hooks.mdimperative-control.mdindex.mdtransform-system.md
tile.json

tessl/npm-react-spring--web

React DOM support for the react-spring animation library with spring-physics based animations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@react-spring/web@10.0.x

To install, run

npx @tessl/cli install tessl/npm-react-spring--web@10.0.0

index.mddocs/

@react-spring/web

@react-spring/web provides React DOM-specific implementation of the react-spring animation library, enabling spring-physics based animations for web applications. It serves as the web target for the cross-platform react-spring ecosystem, offering animated components and hooks that integrate seamlessly with React DOM.

Package Information

  • Package Name: @react-spring/web
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @react-spring/web

Core Imports

import { 
  animated, 
  useSpring, 
  useTransition, 
  useScroll,
  useResize,
  useInView,
  Spring,
  Trail,
  Transition,
  Controller,
  SpringValue,
  to,
  config 
} from "@react-spring/web";

For CommonJS:

const { 
  animated, 
  useSpring, 
  useTransition, 
  useScroll,
  useResize,
  useInView,
  Spring,
  Trail,
  Transition,
  Controller,
  SpringValue,
  to,
  config 
} = require("@react-spring/web");

Basic Usage

import { animated, useSpring, useTransition } from "@react-spring/web";

// Simple spring animation
function FadeBox() {
  const styles = useSpring({
    from: { opacity: 0 },
    to: { opacity: 1 },
  });

  return <animated.div style={styles}>Hello World</animated.div>;
}

// List transitions
function TodoList({ items }) {
  const transitions = useTransition(items, {
    from: { opacity: 0, transform: 'translateY(-20px)' },
    enter: { opacity: 1, transform: 'translateY(0px)' },
    leave: { opacity: 0, transform: 'translateY(-20px)' },
  });

  return transitions((style, item) => (
    <animated.div style={style}>{item.text}</animated.div>
  ));
}

Architecture

@react-spring/web is built around several key components:

  • Animated Components: DOM-specific animated primitives for HTML and SVG elements
  • Animation Hooks: React hooks providing declarative animation control
  • Transform System: Specialized CSS transform handling with optimizations
  • Value Application: Direct DOM manipulation for optimal performance
  • Spring Physics: Natural motion curves based on physical principles

Capabilities

Animated Components

Core animated DOM elements supporting all HTML and SVG tags with spring-powered animations.

const animated: {
  <T extends ElementType>(component: T): AnimatedComponent<T>;
} & {
  [Tag in keyof JSX.IntrinsicElements]: AnimatedComponent<Tag>;
};

const a: typeof animated;

Animated Components

Animation Hooks

React hooks for declarative animation control including springs, transitions, trails, and utility hooks.

function useSpring<Props extends object>(
  props: UseSpringProps<Props>
): SpringValues<PickAnimated<Props>>;

function useTransition<Item, Props extends object>(
  data: OneOrMore<Item>,
  props: UseTransitionProps<Item, Props>
): TransitionFn<Item, PickAnimated<Props>>;

function useTrail<Props extends object>(
  length: number,
  props: UseTrailProps<Props>
): SpringValues<PickAnimated<Props>>[];

Animation Hooks

Transform System

Web-specific transform handling with optimized CSS transform generation and shorthand properties.

interface TransformProps {
  x?: Length;
  y?: Length;
  z?: Length;
  rotate?: Angle;
  scale?: number | readonly [number, number];
  transform?: string;
  translateX?: Length;
  translateY?: Length;
  translateZ?: Length;
  rotateX?: Angle;
  rotateY?: Angle;
  rotateZ?: Angle;
  scaleX?: number;
  scaleY?: number;
  scaleZ?: number;
}

Transform System

Imperative Control

Classes and utilities for imperative animation control and advanced use cases.

class Controller<State extends Lookup = Lookup> {
  start(props?: ControllerUpdate<State>): Promise<AnimationResult<State>>;
  stop(keys?: OneOrMore<string>): this;
  update(props: ControllerUpdate<State>): this;
}

class SpringValue<T = any> extends FrameValue<T> {
  start(props?: SpringUpdate<T>): Promise<AnimationResult<SpringValue<T>>>;
  stop(): this;
  set(value: T | FluidValue<T>): this;
}

Imperative Control

Declarative Components

React components providing declarative animation control with render props pattern.

/**
 * Declarative spring animation component
 * @param props - Spring configuration with children render prop
 * @returns JSX element from children function
 */
function Spring<State extends object>(
  props: SpringComponentProps<State>
): JSX.Element | null;

/**
 * Declarative trail animation component for staggered animations
 * @param props - Trail configuration with items and children render prop
 * @returns JSX element from children function
 */
function Trail<Item, Props extends object>(
  props: TrailComponentProps<Item, Props>
): JSX.Element | null;

/**
 * Declarative transition animation component for entering/leaving items
 * @param props - Transition configuration with items and children render prop
 * @returns JSX element from children function
 */
function Transition<Item, Props extends object>(
  props: TransitionComponentProps<Item, Props>
): JSX.Element;

interface SpringComponentProps<State extends object> extends UseSpringProps<State> {
  /** Render prop function receiving spring values */
  children: (values: SpringValues<State>) => React.JSX.Element | null;
}

interface TrailComponentProps<Item, Props extends object> extends UseSpringProps<Props> {
  /** Array of items to animate */
  items: readonly Item[];
  /** Render prop function for each item with spring values */
  children: (
    item: Item,
    index: number
  ) => ((values: SpringValues<PickAnimated<Props>>) => ReactNode) | Falsy;
}

interface TransitionComponentProps<Item, Props extends object = any> extends UseTransitionProps<Item, Props> {
  /** Items to transition */
  items: OneOrMore<Item>;
  /** Render prop function for transition states */
  children: TransitionFn<Item, PickAnimated<Props>>;
}

Utilities

Utility functions for advanced animation control, easing, and React integration.

/**
 * Map the value of one or more dependencies using interpolation
 * @param source - Source values to interpolate
 * @param args - Interpolation configuration or function
 * @returns Interpolation instance
 */
const to: Interpolator;

/**
 * @deprecated Use the `to` export instead
 * Map the value of one or more dependencies using interpolation
 * @param source - Source values to interpolate
 * @param args - Interpolation configuration or function
 * @returns Interpolation instance
 */
const interpolate: Interpolator;

interface Interpolator {
  // Tuple of parent values
  <Input extends ReadonlyArray<any>, Output>(
    parents: Input,
    interpolator: (...args: Interpolated<Input>) => Output
  ): Interpolation<Output>;

  // Single parent value
  <Input, Output>(
    parent: FluidValue<Input> | Input,
    interpolator: InterpolatorFn<Input, Output>
  ): Interpolation<Output>;

  // Interpolation config
  <Out>(
    parents: OneOrMore<FluidValue>,
    config: InterpolatorConfig<Out>
  ): Interpolation<Animatable<Out>>;

  // Range shortcuts
  <Out>(
    parents: OneOrMore<FluidValue<number>> | FluidValue<number[]>,
    range: readonly number[],
    output: readonly Constrain<Out, Animatable>[],
    extrapolate?: ExtrapolateType
  ): Interpolation<Animatable<Out>>;
}

/**
 * Create custom interpolation functions
 * @param args - Interpolation configuration
 * @returns Interpolation function
 */
function createInterpolator<Input, Output>(
  args: InterpolatorArgs<Input, Output>
): (input: Input) => Output;

/**
 * SSR-safe useLayoutEffect hook
 * Same as useLayoutEffect in browser, useEffect on server
 */
const useIsomorphicLayoutEffect: typeof useLayoutEffect;

/**
 * Hook to respect user's motion preferences
 * @returns True if user prefers reduced motion
 */
function useReducedMotion(): boolean;

/**
 * Collection of easing functions for animations
 */
const easings: {
  linear: (t: number) => number;
  easeInQuad: (t: number) => number;
  easeOutQuad: (t: number) => number;
  easeInOutQuad: (t: number) => number;
  easeInCubic: (t: number) => number;
  easeOutCubic: (t: number) => number;
  easeInOutCubic: (t: number) => number;
  easeInQuart: (t: number) => number;
  easeOutQuart: (t: number) => number;
  easeInOutQuart: (t: number) => number;
  easeInQuint: (t: number) => number;
  easeOutQuint: (t: number) => number;
  easeInOutQuint: (t: number) => number;
  easeInSine: (t: number) => number;
  easeOutSine: (t: number) => number;
  easeInOutSine: (t: number) => number;
  easeInExpo: (t: number) => number;
  easeOutExpo: (t: number) => number;
  easeInOutExpo: (t: number) => number;
  easeInCirc: (t: number) => number;
  easeOutCirc: (t: number) => number;
  easeInOutCirc: (t: number) => number;
  easeInBack: (t: number) => number;
  easeOutBack: (t: number) => number;
  easeInOutBack: (t: number) => number;
  easeInElastic: (t: number) => number;
  easeOutElastic: (t: number) => number;
  easeInOutElastic: (t: number) => number;
  easeInBounce: (t: number) => number;
  easeOutBounce: (t: number) => number;
  easeInOutBounce: (t: number) => number;
};

/**
 * Infer animation target values from configuration
 * @param props - Animation configuration
 * @returns Inferred target values
 */
function inferTo(props: any): any;

/**
 * Predefined spring configurations for common animation styles
 */
const config: {
  default: { tension: 170; friction: 26 };
  gentle: { tension: 120; friction: 14 };
  wobbly: { tension: 180; friction: 12 };
  stiff: { tension: 210; friction: 20 };
  slow: { tension: 280; friction: 60 };
  molasses: { tension: 280; friction: 120 };
};

/**
 * Global configuration and frame loop controls
 */
const Globals: {
  assign(props: Partial<GlobalsProps>): void;
  skipAnimation: boolean;
  to: (source: any, args: any) => Interpolation;
};

/**
 * Advance all animations by the given time
 * @param dt - Delta time in milliseconds
 */
const update: (dt?: number) => void;

Common Types

type Length = number | string;
type Angle = number | string;

type AnimatedProps<Props extends object> = {
  [P in keyof Props]: P extends 'ref' | 'key'
    ? Props[P]
    : AnimatedProp<Props[P]>;
};

type UseSpringProps<Props extends object = any> = ControllerUpdate<
  PickAnimated<Props>
> & {
  ref?: SpringRef<PickAnimated<Props>>;
};

interface SpringValues<State extends Lookup> {
  [key: string]: SpringValue;
}

type TransitionFn<Item, State extends Lookup> = (
  style: SpringValues<State>,
  item: Item,
  transition: TransitionState<Item>,
  index: number
) => React.ReactElement;