Tween - Basics

The Tween API is the foundation of FasterMotion, providing a unified interface to animate DOM element properties with triggers, scroll integration, and full playback control.

FasterMotion.dom()

The recommended high-level API for DOM animations with built-in trigger modes, scroll integration, and auto-cleanup.

Syntax

FasterMotion.dom(config: DomConfig): Animation

Basic Usage

import { FasterMotion } from 'faster-motion';

// Animate to target values
FasterMotion.dom({
  target: '#box',
  to: {
    x: 200,
    rotation: 360,
    scale: 1.2
  },
  duration: 1000,
  ease: 'spring.bouncy'
});

Try it: Move, Rotate & Scale

FasterMotion.dom({
  target: '#box',
  to: { x: 200, rotation: 360, scale: 1.2 },
  duration: 1000,
  ease: 'spring.bouncy'
});

Configuration

Complete configuration object for DOM animations.

target

Type: string | HTMLElement

CSS selector or HTMLElement to animate.

// Selector
FasterMotion.dom({
  target: '#box',
  to: { x: 100 }
});

// Direct element
const el = document.querySelector('#box');
FasterMotion.dom({
  target: el,
  to: { x: 100 }
});

to

Type: object

Target property values to animate to.

FasterMotion.dom({
  target: '#box',
  to: {
    x: 200,           // translateX
    y: 100,           // translateY
    rotation: 360,    // rotate (degrees)
    scale: 1.2,       // uniform scale
    opacity: 1        // opacity
  }
});

from

Type: object

Starting property values (animates from these to current or to values).

// Fade in from invisible
FasterMotion.dom({
  target: '#box',
  from: { opacity: 0, y: 50 },
  to: { opacity: 1, y: 0 },
  duration: 800
});

Try it: Fade In Animation

FasterMotion.dom({
  target: '#box',
  from: { opacity: 0, y: 50 },
  to: { opacity: 1, y: 0 },
  duration: 800
});

Animatable Properties

Transform Properties:

x, y - Translation (pixels)
rotation - Rotation (degrees)
scale, scaleX, scaleY - Scale values

Visual Properties:

opacity - Opacity (0 to 1)
backgroundColor - Background color
color - Text color
borderRadius - Border radius

Timing

Control animation duration, easing, and delays.

duration

Type: number | Default: 1000

Animation duration in milliseconds.

// Fast animation
FasterMotion.dom({
  target: '#box',
  to: { x: 100 },
  duration: 300
});

// Slow animation
FasterMotion.dom({
  target: '#box',
  to: { x: 100 },
  duration: 2000
});

ease

Type: string | Default: 'linear'

Easing function name.

FasterMotion.dom({
  target: '#box',
  to: { x: 200 },
  duration: 1000,
  ease: 'spring.bouncy'
});

// Common easing functions
'linear'
'curve1.in', 'curve1.out', 'curve1.inOut'
'curve2.in', 'curve2.out', 'curve2.inOut'
'spring.smooth', 'spring.bouncy', 'spring.snappy'

delay

Type: number | Default: 0

Delay before animation starts (milliseconds).

FasterMotion.dom({
  target: '#box',
  to: { x: 100 },
  delay: 500        // Wait 500ms before starting
});

Relative Values

Use operators to animate relative to current values.

// += adds to current value
FasterMotion.dom({
  target: '#box',
  to: { x: '+=100' },  // Move 100px right from current position
  duration: 500
});

// -= subtracts from current value
FasterMotion.dom({
  target: '#box',
  to: { x: '-=50' },   // Move 50px left from current position
  duration: 500
});

// *= multiplies current value
FasterMotion.dom({
  target: '#box',
  to: { scale: '*=1.5' }, // 1.5x bigger
  duration: 500
});

// /= divides current value
FasterMotion.dom({
  target: '#box',
  to: { scale: '/=1.5' }, // Shrink back
  duration: 500
});

Try it: Relative Values

// += adds to current value
FasterMotion.dom({
  target: '#box',
  to: { x: '+=100' },
  duration: 500
});

// -= subtracts from current value
FasterMotion.dom({
  target: '#box',
  to: { x: '-=50' },
  duration: 500
});

// *= multiplies current value
FasterMotion.dom({
  target: '#box',
  to: { scale: '*=1.5' },
  duration: 500
});

// /= divides current value
FasterMotion.dom({
  target: '#box',
  to: { scale: '/=1.5' },
  duration: 500
});

Common Patterns

Fade In on Load

FasterMotion.dom({
  target: '.content',
  from: { opacity: 0, y: 30 },
  to: { opacity: 1, y: 0 },
  duration: 800,
  ease: 'curve2.out'
});

Hover Scale

FasterMotion.dom({
  target: '.button',
  to: { scale: 1.1 },
  duration: 300,
  trigger: 'hover'
});

Sequential Chain

FasterMotion.dom({
  target: '#box1',
  to: { x: 100 },
  duration: 500,
  onComplete: () => {
    FasterMotion.dom({
      target: '#box2',
      to: { x: 100 },
      duration: 500
    });
  }
});

TypeScript Support

import { FasterMotion } from 'faster-motion';

FasterMotion.dom({
  target: '#box',
  to: { x: 200, rotation: 360 },
  duration: 1000,
  ease: 'spring.bouncy',
  onComplete: () => console.log('Done')
});

Next Steps

Advanced Features - Callbacks, playback control, iterations
Triggers & Scroll - Interactive triggers and scroll animations
Timeline - Sequence multiple tweens
Easing - Easing functions reference

Tween - Basics

Try it: Move, Rotate & Scale

Try it: Fade In Animation

Try it: Relative Values

On this page