use-spring-transition

Utilize react-transition-group functionality into the hook with spring animation support

Usage

Demo

1// Menu.tsx
2import cx from 'clsx';
3import { useSpringTransition } from 'use-spring-transition';
4import styles from './Menu.module.css';
5
6const Menu = () => {
7  const [opened, setOpened] = useState(false);
8  const transition = useSpringTransition(
9    opened,
10    { mass: 1, stiffness: 80, damping: 20 },
11    {
12      from: 0,
13      to: 500,
14    },
15  );
16
17  if (transition.stage === 'closed') {
18    return null;
19  }
20
21  return (
22    <div
23      className={styles.menu}
24      style={{ height: transition.springValue }}
25    >
26      Menu
27    </div>
28  );
29};

1/* Menu.module.css */
2.menu {
3  width: 500px;
4}

1// Viewer.tsx
2import cx from 'clsx';
3import { useSpringTransition } from 'use-spring-transition';
4import styles from './Viewer.module.css';
5
6const Viewer = ({
7  images,
8}: {
9  images: {
10    id: string;
11    url: sring;
12    alt: string;
13  }[];
14}) => {
15  const [currentIndex, setCurrentIndex] =
16    useState(0);
17  const transitions = useSpringTransition(
18    images[currentIndex],
19    { mass: 1, stiffness: 180, damping: 30 },
20    { from: 100, to: { open: 0, close: -100 } },
21  );
22
23  return (
24    <div className={styles.viewer}>
25      {transitions.map(
26        (transition) =>
27          transition.value && (
28            <img
29              className={cx(
30                styles.image,
31                styles[transition.stage],
32              )}
33              style={{
34                transform: `translate3d(${transition.springValue}px, 0, 0)`,
35              }}
36              key={transition.value.id}
37              src={transition.value.url}
38              alt={transition.value.alt}
39            />
40          ),
41      )}
42    </div>
43  );
44};

1/* Viewer.module.css */
2.viewer {
3  height: 100%;
4  width: 100%;
5  position: relative;
6}
7
8.image {
9  height: 100%;
10  width: 100%;
11}
12
13.image.close,
14.image.closing {
15  position: absolute;
16  top: 0;
17  left: 0;
18}

API

SpringOptions

1interface SpringOptions {
2  mass?: number;
3  stiffness?: number;
4  damping?: number;
5  initialVelocity?: number;
6  threshold?: number;
7}

Defaults:

1mass: 1;
2stiffness: 100;
3damping: 10;
4initialVelocity: 0;
5threshold: 0.01;

Description:

• mass, stiffness, damping, initialVelocity - spring animation configuration
• threshold - special property for ending a spring animation when spring value difference on each frame lower than threshold 10 times in a row*.

*spring animation can generate a small difference on each frame before reach to value. For example, we want to animate opacity from 0 to 1. Spring animation can generate 0.991233, 0.992533, 0.993334... in a near minute before reach 1 (or never reach at all). To avoid this long useless animation we can finish animation when spring value is near the to value. That's why we use threshold property.

Stage

1type Stage =
2  // closed -> opened transition started
3  | 'open'
4  // closed -> opened transition in proccess
5  | 'opening'
6  // closed -> opened transition ended
7  | 'opened'
8  // opened -> closed transition started
9  | 'close'
10  // opened -> closed transition in proccess
11  | 'closing'
12  // opened -> closed transition ended
13  | 'closed';

Values

1interface Values {
2  from: number;
3  to:
4    | number
5    // you can use different "to" for closed -> opened and opened -> closed transitions
6    | {
7        open: number;
8        close: number;
9      };
10}

Defaults:

1{ from: 0, to: 1 }

Options

1type Options =
2  // spring
3  | SpringOptions
4  // transiton-duration
5  | number
6  // you can use different animations for closed -> opened and opened -> closed transitions
7  | {
8      close: SpringOptions | number;
9      open: SpringOptions | number;
10    };

Defaults:

1{
2}

HookOptions

1interface HookOptions<T> {
2  // item unique key getter (key can be same as you use for "key" prop)
3  getKey?: (item: T) => any;
4  // keep transitions with "closed" stage (they filtered by default)
5  keepClosed?: boolean;
6}

Defaults:

1getKey: (item) => item;
2keepClosed: false;

Transition

1interface Transition<T> {
2  value: T;
3  stage: Stage;
4  // animated value (it can be height or opacity, for example)
5  springValue: number;
6}

useSpringTransition

1// as open/close transition
2export function useSpringTransition(
3  opened: boolean,
4  options?: Options,
5  values?: Values,
6): Omit<Transition<boolean>, 'value'>;
7
8// as value transition
9export function useSpringTransition<T>(
10  value: T,
11  options?: Options,
12  values?: Values,
13  hookOptions?: HookOptions<T>,
14): Transition<T>[];
15
16// as list transition
17export function useSpringTransition<T>(
18  value: T[],
19  options?: Options,
20  values?: Values,
21  hookOptions?: HookOptions<T>,
22): Transition<T>[];