Guides · 01

Werte und style

Einen Wert in einer Komponente halten, Ausgaben mit calc() ableiten und wählen, wo die CSS-Variable geschrieben wird.

Einen Wert halten

useAnimatedValue(initial) erstellt einen Value, der der Komponente gehört. Nimm eine Zahl oder einen Record wie { x: 0, opacity: 1 }, dessen Felder eigene Werte sind.

In einem normalen style ist ein Hook-Wert das Token var(--kkwa-…, initial). Updates schreiben diese Variable auf die Elemente, die sie nutzen; React rendert nicht.

Beispiel wird vorbereitet…

JavaScript ist aus. Der Code unten ist das vollständige Beispiel.

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;
}

Mit calc() ableiten

Eine Interpolation ohne Easing sowie add, subtract, multiply oder divide mit einer Konstanten werden zu exakten calc()-Ausdrücken derselben Variablen. Der Browser leitet sie ab; dafür läuft pro Frame kein JavaScript.

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})` }} />;

Beispiel wird vorbereitet…

JavaScript ist aus. Der Code unten ist das vollständige Beispiel.

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;
}

Farben und eigene Berechnungen

Farben, Interpolationen mit Easing, modulo, diffClamp und AnimatedComputed lassen sich nicht als calc() schreiben. useAnimatedCSS(node) gibt ihnen eine eigene CSS-Variable, die JavaScript aktualisiert – mit derselben Lebensdauer wie die Komponente.

Ein solcher Knoten direkt in style wirft einen Fehler, damit die Kosten nie versteckt sind.

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 }} />;

Den Hook ein Rezept verwalten lassen

useAnimated(initial, factory, deps) hält den Wert und jeden Controller, der synchron in der Factory deklariert wird. Es startet beim Mount, startet neu, wenn sich eine Abhängigkeit ändert, und stoppt beim Unmount.

Übergib { autoStart: false } für ereignisgesteuerte Wiedergabe und ruf dann start(), stop() oder reset() auf dem zurückgegebenen Wert auf.

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))` }} />;

Einmal schreiben für viele Elemente

Standardmäßig bekommt jedes Element, dessen Inline-Style den Wert nutzt, die Variable. Mit scope wird die Variable einmal auf einem Container geschrieben und von den Kindern geerbt – die richtige Wahl für Hunderte Elemente.

AnimatedProvider scope={ref} setzt einen Standard-Scope für jeden Hook-Wert darunter.

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>;

Werte in JavaScript lesen

getValue() gibt einen Snapshot zurück, ohne React zu abonnieren. useAnimatedListener(node, fn) ruft dich bei jeder Änderung auf und entfernt den Listener beim Unmount. Nutze ihn fürs Zeichnen auf Canvas oder für Analytics, nicht fürs Rendern.