useValue

The useValue() function is a powerful hook designed to manage and animate values within your React components without triggering unnecessary re-renders. It behaves similarly to a ref, holding the current animation state internally.

This hook returns a tuple: [value, setValue].

• value: The current animated state, which you can directly apply to JSX styles or component props.
• setValue: A function to update the value, which can trigger a smooth animation when used with motion modifiers.

Basic Usage

The primary use case for useValue() is to animate properties. For instance, to animate an element's width:

import React from 'react';
import { animate, useValue, withSpring } from 'react-ui-animate';
import './styles.css';

export default function App() {
  const [width, setWidth] = useValue(100);

  return (
    <div className="container">
      <button
        className="button buttonPrimary"
        onClick={() => setWidth(withSpring(200))}
      >
        Expand
      </button>
      <button
        className="button buttonSecondary"
        onClick={() => setWidth(withSpring(100))}
      >
        Reset
      </button>
      <animate.div
        style={{
          width,
          height: 100,
          backgroundColor: 'teal',
          borderRadius: '8px',
          margin: '20px auto 0',
        }}
      />
    </div>
  );
}

Open Sandbox

Immediate vs. Animated Updates

When you assign a raw value (e.g., setWidth(200)), the property changes immediately without animation. To achieve a smooth transition, you must wrap the target value in a animation modifier like (withTiming or withSpring).

---

Usage

1. Primitive Values (Number & String)

For primitive data types such as numbers or strings, useValue manages a single animated value directly.

Syntax

const [value, setValue] = useValue(initialValue: number | string);

View example

import React from 'react';
import { animate, useValue, withSpring } from 'react-ui-animate';
import './styles.css';

export default function App() {
  const [width, setWidth] = useValue(100);

  return (
    <div className="container">
      <button
        className="button buttonPrimary"
        onClick={() => setWidth(withSpring(200))}
      >
        Expand
      </button>
      <button
        className="button buttonSecondary"
        onClick={() => setWidth(withSpring(100))}
      >
        Reset
      </button>
      <animate.div
        style={{
          width,
          height: 100,
          backgroundColor: 'teal',
          borderRadius: '8px',
          margin: '20px auto 0',
        }}
      />
    </div>
  );
}

Open Sandbox

2. Array of Primitives

You can also animate an array of values. The hook stores the array and you update it similarly:

Syntax

const [arr, setArr] = useValue(initialArray: number[]);

View example

import React from 'react';
import { useValue, withSpring, animate } from 'react-ui-animate';
import '../../styles.css';

export default function App() {
  const [values, setValues] = useValue([0, 0, 0]);

  return (
    <div className="container">
      <button
        className="button buttonPrimary"
        onClick={() => setValues(withSpring([10, 100, 200]))}
      >
        Start
      </button>
      <button
        className="button buttonSecondary"
        onClick={() => setValues([0, 0, 0])}
      >
        Reset
      </button>

      <div style={{ marginTop: 20, display: 'flex', gap: 10, justifyContent: 'center' }}>
        {values.map((value, index) => (
          <animate.div
            key={index}
            style={{
              width: 100,
              height: 100,
              backgroundColor: 'teal',
              translateX: value,
              borderRadius: 8,
            }}
          />
        ))}
      </div>
    </div>
  );
}

Open Sandbox

3. Object of Primitives

You can also initialize useValue with an object whose fields are numbers or strings. The hook returns a matching object

Syntax

const [obj, setObj] = useValue(initialObject: { [key: string]: number | string });

View example

import React from 'react';
import { useValue, withSpring, animate } from 'react-ui-animate';
import '../../styles.css';

export default function App() {
  const [obj, setObj] = useValue({ x: 0, y: 0, width: 100, height: 100 });

  return (
    <div className="container">
      <button
        className="button buttonPrimary"
        onClick={() =>
          setObj(
            withSpring(
              { x: 100, y: 100, width: 200, height: 200 },
              {
                onStart: () => console.log('START'),
                onComplete: () => console.log('Animation complete'),
              }
            )
          )
        }
      >
        Start
      </button>
      <button
        className="button buttonSecondary"
        onClick={() => setObj({ x: 0, y: 0, width: 100, height: 100 })}
      >
        Reset
      </button>

      <animate.div
        style={{
          width: obj.width,
          height: 100,
          backgroundColor: 'teal',
          margin: '20px auto 0',
          translateX: obj.x,
          translateY: obj.y,
          borderRadius: 8,
        }}
      />
    </div>
  );
}

Open Sandbox