Guides · 01

Valeurs et style

Gérer une valeur dans un composant, dériver des sorties avec calc() et choisir où la variable CSS est écrite.

Gérer une valeur

useAnimatedValue(initial) crée une Value qui appartient au composant. Utilisez un nombre, ou un enregistrement comme { x: 0, opacity: 1 } dont chaque champ est une valeur distincte.

Dans un style ordinaire, une valeur de hook est le jeton var(--kkwa-…, initial). Les mises à jour écrivent cette variable sur les éléments qui l’utilisent ; React ne se rend pas.

Préparation de l’exemple…

JavaScript est désactivé. Le code ci-dessous est l’exemple complet.

App.jsx

import { timing, useAnimatedValue } from '@kkwaenggwari/animated';
import './styles.css';

export default function App({ duration = 600 }) {
  const progress = useAnimatedValue(1);

  const toggle = () => {
    const toValue = progress.getValue() > 0.5 ? 0 : 1;
    timing(progress, { toValue, duration }).start();
  };

  return (
    <div className="stage">
      <button type="button" onClick={toggle}>
        Toggle
      </button>
      <div className="box" style={{ opacity: progress }}>
        Ready
      </div>
    </div>
  );
}

styles.css

.stage {
  display: flex;
  align-items: center;
  gap: 24px;
  min-height: 200px;
  padding: 28px;
}

button {
  min-height: 44px;
  padding: 0 20px;
  border: 0;
  border-radius: 999px;
  background: #2854ff;
  color: #fff;
  font: inherit;
  font-weight: 650;
  cursor: pointer;
}

.box {
  display: grid;
  place-items: center;
  width: 140px;
  height: 140px;
  border-radius: 24px;
  background: #16181d;
  color: #fff;
  font-weight: 700;
}

Dériver avec calc()

Une interpolation sans easing et add, subtract, multiply ou divide par une constante deviennent des expressions calc() exactes de la même variable. Le navigateur les calcule ; aucun JavaScript ne s’exécute pour elles à chaque image.

Slide.jsx

const progress = useAnimatedValue(0);

// A linear interpolation of a hook value is a calc() of the same CSS variable.
const x = progress.interpolate({ inputRange: [0, 1], outputRange: ['0px', '180px'] });
const half = multiply(progress, 0.5);

<div style={{ opacity: half, transform: `translateX(${x})` }} />;

Préparation de l’exemple…

JavaScript est désactivé. Le code ci-dessous est l’exemple complet.

App.jsx

import { spring, useAnimatedValue } from '@kkwaenggwari/animated';
import './styles.css';

const colors = ['#2854ff', '#4a6bff', '#8fb0ff', '#7d9bff', '#5c7cff'];

export default function App({ distance = 220, spread = 0.12 }) {
  const progress = useAnimatedValue(0);

  const toggle = () => {
    const toValue = progress.getValue() < 0.5 ? 1 : 0;
    spring(progress, { toValue, stiffness: 150, damping: 16 }).start();
  };

  return (
    <div className="stage">
      <button type="button" onClick={toggle}>
        Move all
      </button>
      <div className="lanes">
        {colors.map((color, index) => {
          const start = index * spread;
          const x = progress.interpolate({
            inputRange: [start, start + 1 - spread * 4],
            outputRange: ['0px', `${distance}px`],
            extrapolate: 'clamp',
          });
          const turn = progress.interpolate({
            inputRange: [0, 1],
            outputRange: ['0deg', `${90 + index * 45}deg`],
          });
          return (
            <div key={color} className="lane">
              <span style={{ background: color, transform: `translateX(${x}) rotate(${turn})` }} />
            </div>
          );
        })}
      </div>
    </div>
  );
}

styles.css

.stage {
  display: grid;
  gap: 20px;
  padding: 28px;
}

button {
  justify-self: start;
  min-height: 44px;
  padding: 0 20px;
  border: 0;
  border-radius: 999px;
  background: #2854ff;
  color: #fff;
  font: inherit;
  font-weight: 650;
  cursor: pointer;
}

.lanes {
  display: grid;
  gap: 10px;
}

.lane {
  height: 36px;
  max-width: 320px;
  border-radius: 999px;
  background: #f5f6fb;
}

.lane span {
  display: block;
  width: 36px;
  height: 36px;
  border-radius: 10px;
}

Couleurs et calculs personnalisés

Les couleurs, les interpolations avec easing, modulo, diffClamp et AnimatedComputed ne peuvent pas s’écrire en calc(). useAnimatedCSS(node) leur donne leur propre variable CSS, mise à jour par JavaScript, avec la même durée de vie que le composant.

Utiliser un tel nœud directement dans style lève une erreur : le coût n’est jamais caché.

Glow.jsx

const progress = useAnimatedValue(0);

// Colors and eased curves are not calc() expressions: give them their own CSS value.
const color = useAnimatedCSS(
  progress.interpolate({ inputRange: [0, 1], outputRange: ['#3d3bf3', '#22b8f0'] }),
);

<div style={{ background: color }} />;

Confier une recette au hook

useAnimated(initial, factory, deps) gère la valeur et chaque contrôleur déclaré de façon synchrone dans la factory. Elle démarre au montage, redémarre quand une dépendance change et s’arrête au démontage.

Passez { autoStart: false } pour une lecture déclenchée par un événement, puis appelez start(), stop() ou reset() sur la valeur renvoyée.

Intro.jsx

const intro = useAnimated(
  { opacity: 0, y: 24 },
  (value) => {
    parallel([
      timing(value.opacity, { toValue: 1, duration: 400 }),
      spring(value.y, { toValue: 0, stiffness: 220, damping: 20 }),
    ]);
  },
  [],
);

<section style={{ opacity: intro.opacity, transform: `translateY(calc(${intro.y} * 1px))` }} />;

Écrire une fois pour de nombreux éléments

Par défaut, chaque élément dont le style en ligne utilise la valeur reçoit la variable. Avec scope, la variable est écrite une fois sur un conteneur et héritée par ses enfants : le bon choix pour des centaines d’éléments.

AnimatedProvider scope={ref} définit un scope par défaut pour toutes les valeurs de hook en dessous.

Field.jsx

const field = useRef(null);

// Written once on the field; every child that uses the value inherits it.
const wave = useAnimatedValue(0, { scope: field });

<div ref={field}>
  {items.map((item) => (
    <i key={item} style={{ transform: `rotate(calc(${wave} * 1turn))` }} />
  ))}
</div>;

Lire les valeurs en JavaScript

getValue() renvoie un instantané sans abonner React. useAnimatedListener(node, fn) vous appelle à chaque changement et retire le listener au démontage. Servez-vous-en pour dessiner dans un canvas ou pour des statistiques, pas pour le rendu.