SSGOI LogoSSGOI

Physics Options

Natural animations through various physics engines including spring and inertia

Physics Options

SSGOI 4.0 supports various physics engines to create natural and smooth animations. From spring physics to inertia-based animations, you can choose the optimal motion for each situation.

PhysicsOptions Interface

All transitions can be configured with physics engines through the physics option:

type PhysicsOptions = {
  spring?: SpringConfig;           // Spring physics (ease-out effect)
  inertia?: InertiaConfig;         // Inertia physics (ease-in effect)
  integrator?: () => Integrator;   // Custom integrator
};

Each physics engine provides different animation characteristics, and you can choose according to your needs.

Spring Physics

Spring physics generates ease-out effects and is suitable for most UI animations.

Basic Usage

import { fade } from '@ssgoi/react/view-transitions';

// Basic spring configuration
fade({
  physics: {
    spring: {
      stiffness: 300,
      damping: 30
    }
  }
})

Spring Configuration Options

type SpringConfig = {
  stiffness: number;        // Spring stiffness (higher = faster animation)
  damping: number;          // Damping coefficient (higher = less oscillation)
  doubleSpring?: boolean | number | {
    stiffness: number;
    damping: number;
  };
};
  • stiffness: Controls the spring's tension. Higher values create faster animations.
  • damping: Controls the resistance. Higher values reduce oscillation and create smoother stops.
  • doubleSpring: Double spring configuration for ease-in-out effect

Double Spring

Using the doubleSpring option, you can chain two springs to create an ease-in-out effect:

// Automatic configuration (true)
fade({
  physics: {
    spring: {
      stiffness: 300,
      damping: 30,
      doubleSpring: true  // Follower spring is automatically configured
    }
  }
})

// Ratio configuration (0~1)
fade({
  physics: {
    spring: {
      stiffness: 300,
      damping: 30,
      doubleSpring: 0.5  // Follower spring stiffness ratio (lower = stronger ease-in)
    }
  }
})

// Manual configuration
fade({
  physics: {
    spring: {
      stiffness: 300,
      damping: 30,
      doubleSpring: {
        stiffness: 150,   // Follower spring configuration
        damping: 20
      }
    }
  }
})

Inertia Physics

Inertia physics generates ease-in effects and is suitable for directional transitions (drill, slide, etc.).

Basic Usage

import { drill } from '@ssgoi/react/view-transitions';

drill({
  direction: 'enter',
  physics: {
    inertia: {
      acceleration: 20,
      resistance: 1.5
    }
  }
})

Inertia Configuration Options

type InertiaConfig = {
  acceleration: number;              // Acceleration force (higher = faster acceleration)
  resistance: number;                // Resistance coefficient (higher = lower final velocity)
  resistanceType?: 'linear' | 'quadratic';  // Resistance type
};
  • acceleration: Controls the acceleration force. Higher values mean faster acceleration.
  • resistance: Controls the resistance coefficient. Higher values result in lower final velocity.
  • resistanceType: Resistance type (linear: linear, quadratic: quadratic function)

Usage Examples

import { slide } from '@ssgoi/react/view-transitions';

// Smooth ease-in effect
slide({
  direction: 'up',
  physics: {
    inertia: {
      acceleration: 15,
      resistance: 1.2,
      resistanceType: 'linear'
    }
  }
})

// Fast ease-in effect
slide({
  direction: 'down',
  physics: {
    inertia: {
      acceleration: 30,
      resistance: 2.0,
      resistanceType: 'quadratic'
    }
  }
})

Spring Presets

Pre-defined spring configurations are provided to easily create various animation feels without manually adjusting physics values.

Importing Presets

import { config } from '@ssgoi/react/presets';
// or
import { config } from '@ssgoi/svelte/presets';
// or
import { config } from '@ssgoi/angular/presets';

// Use in transitions
transition({
  physics: { spring: config.gentle },
  tick: (progress) => {
    // Animation logic
  }
})

You can also import individual presets:

import { gentle, wobbly, stiff } from '@ssgoi/react/presets';

transition({
  physics: { spring: gentle },
  // ...
})

Available Presets

default

A balanced animation suitable for most use cases.

  • stiffness: 170
  • damping: 26
  • Use case: General purpose transitions

gentle

Smooth and calm transitions with subtle movement.

  • stiffness: 120
  • damping: 14
  • Use case: Elegant, professional interfaces

wobbly

Bouncy and playful animations with noticeable spring effect.

  • stiffness: 180
  • damping: 12
  • Use case: Fun, interactive elements

stiff

Quick and responsive animations with minimal overshoot.

  • stiffness: 210
  • damping: 20
  • Use case: Snappy UI responses, tooltips

slow

Deliberate and measured animations.

  • stiffness: 280
  • damping: 60
  • Use case: Important state changes, reveals

molasses

Very slow and viscous movement.

  • stiffness: 150
  • damping: 60
  • Use case: Dramatic effects, loading states

Custom Physics Configuration

You can create your own physics configuration instead of using presets:

Custom Spring

transition({
  physics: {
    spring: {
      stiffness: 150,
      damping: 15
    }
  },
  // ...
})

Custom Inertia

transition({
  physics: {
    inertia: {
      acceleration: 25,
      resistance: 1.8,
      resistanceType: 'linear'
    }
  },
  // ...
})

Combining Physics Engines

Some transitions allow using different physics engines for IN and OUT animations:

fade({
  inPhysics: {
    spring: {
      stiffness: 300,
      damping: 30
    }
  },
  outPhysics: {
    inertia: {
      acceleration: 20,
      resistance: 1.5
    }
  }
})

Examples

Using Physics Options in View Transitions

import { Ssgoi } from '@ssgoi/react';
import { config } from '@ssgoi/react/presets';
import { fade, drill } from '@ssgoi/react/view-transitions';

const ssgoiConfig = {
  // Using spring preset
  defaultTransition: fade({
    physics: { spring: config.gentle }
  }),
  transitions: [
    {
      from: '/home',
      to: '/about',
      transition: fade({
        physics: {
          spring: {
            stiffness: 300,
            damping: 30,
            doubleSpring: true  // ease-in-out effect
          }
        }
      })
    },
    {
      from: '/products',
      to: '/products/*',
      transition: drill({
        direction: 'enter',
        physics: {
          inertia: {
            acceleration: 20,
            resistance: 1.5
          }
        }
      })
    }
  ]
};

Using Physics Options in Element Transitions

import { transition } from '@ssgoi/react';
import { config } from '@ssgoi/react/presets';

// Using spring preset
const fadeIn = transition({
  physics: { spring: config.slow },
  tick: (progress) => ({
    opacity: progress,
    transform: `translateY(${(1 - progress) * 20}px)`
  })
});

// Using custom spring
const slideIn = transition({
  physics: {
    spring: {
      stiffness: 200,
      damping: 25,
      doubleSpring: 0.4  // ease-in-out effect
    }
  },
  tick: (progress) => ({
    opacity: progress,
    transform: `translateX(${(1 - progress) * 50}px)`
  })
});

Physics Engine Selection Guide

Each physics engine provides different animation feels:

Spring Physics

  • Effect: ease-out (starts fast, ends slowly)
  • Suitable for:
    • Fade in/out
    • Modal open/close
    • Tooltip display
    • Element appear/disappear
  • Advantages: Natural and smooth deceleration, most widely used in UI

Double Spring

  • Effect: ease-in-out (starts slow, progresses fast, ends slowly)
  • Suitable for:
    • Long distance movements
    • Page transitions
    • Important state changes
  • Advantages: Elegant and refined feel, smooth start and end

Inertia Physics

  • Effect: ease-in (starts slow, ends fast)
  • Suitable for:
    • Drill transitions (zoom in/out)
    • Slide transitions (directional movement)
    • Scroll effects
  • Advantages: Feels like user-initiated motion, expresses physical inertia

Tips and Best Practices

1. Use Spring by Default

Spring physics is most suitable for most UI animations:

fade({ physics: { spring: config.default } })

2. Use Inertia for Directional Transitions

When pages move in a specific direction, inertia physics feels more natural:

drill({ direction: 'enter', physics: { inertia: { acceleration: 20, resistance: 1.5 } } })

3. Add Elegance with Double Spring

Use doubleSpring for important page transitions to create a more refined feel:

fade({ physics: { spring: { ...config.gentle, doubleSpring: true } } })

4. Start with Presets

Try presets before setting custom values:

// Start with preset
physics: { spring: config.gentle }

// Adjust if needed
physics: { spring: { ...config.gentle, stiffness: 250 } }

5. Maintain Consistency

Use the same physics configuration for similar animations throughout your app:

const appPhysics = {
  modal: { spring: config.stiff },
  page: { spring: { ...config.gentle, doubleSpring: true } },
  element: { spring: config.default }
};