Guide · 01

Valori e stile

Possiedi un valore in un componente, ricava output con calc() e scegli dove viene scritta la variabile CSS.

Possiedi un valore

useAnimatedValue(initial) crea un Value che appartiene al componente. Usa un numero, oppure un record come { x: 0, opacity: 1 } i cui campi sono valori separati.

In un normale style, il valore di un hook è il token var(--kkwa-…, initial). Gli aggiornamenti scrivono quella variabile sugli elementi che la usano; React non si renderizza.

Preparazione dell’esempio…

JavaScript è disattivato. Il codice qui sotto è l’esempio completo.

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

Ricava con calc()

Un’interpolazione senza easing e add, subtract, multiply o divide per una costante diventano espressioni calc() esatte della stessa variabile. Le ricava il browser; per loro non viene eseguito JavaScript a ogni frame.

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

Preparazione dell’esempio…

JavaScript è disattivato. Il codice qui sotto è l’esempio completo.

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

Colori e calcoli personalizzati

Colori, interpolazioni con easing, modulo, diffClamp e AnimatedComputed non si possono scrivere come calc(). useAnimatedCSS(node) dà loro una variabile CSS propria, aggiornata da JavaScript, con la stessa vita del componente.

Usare un nodo del genere direttamente in style lancia un errore, così il costo non è mai nascosto.

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

Lascia che l’hook possieda una ricetta

useAnimated(initial, factory, deps) possiede il valore e ogni controller dichiarato in modo sincrono nella factory. Parte al montaggio, riparte quando cambia una dipendenza e si ferma allo smontaggio.

Passa { autoStart: false } per una riproduzione guidata dagli eventi, poi chiama start(), stop() o reset() sul valore restituito.

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

Scrivi una volta per molti elementi

Di default, ogni elemento il cui style inline usa il valore riceve la variabile. Con scope, la variabile viene scritta una volta su un contenitore ed ereditata dai figli: la scelta giusta per centinaia di elementi.

AnimatedProvider scope={ref} imposta uno scope predefinito per tutti i valori degli hook al suo interno.

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

Leggi i valori in JavaScript

getValue() restituisce un’istantanea senza iscrivere React. useAnimatedListener(node, fn) ti chiama a ogni modifica e rimuove il listener allo smontaggio. Usalo per disegnare su canvas o per le analytics, non per il rendering.