Fundamentos do React Spring: hook useSpring

Animações CSS tradicionais usam uma duração fixa: a animação é executada durante X milissegundos e para. react-spring anima valores usando física de molas — a animação é impulsionada por tensão (rigidez da mola) e atrito (quanto a mola resiste ao movimento). Isso produz um movimento que desacelera naturalmente e transmite uma sensação orgânica.

O gancho useSpring({ from, to }) define um valor animado. Você especifica os valores iniciais em from e os valores de destino em to. useSpring retorna um objeto de molas no qual cada chave é um SpringValue — uma versão animada do valor numérico ou de cor correspondente.

A opção config controla o comportamento da mola. tensão (padrão 170) controla a rigidez — valores maiores fazem o movimento atingir o destino mais rapidamente. atrito (padrão 26) controla o amortecimento — valores menores produzem mais quique. massa (padrão 1) adiciona inércia. Juntos, esses três valores definem o caráter da animação.

react-spring vem com configurações predefinidas que você pode usar sem ajustar os valores: config.default é equilibrada e de uso geral, config.gentle é lenta e suave, config.wobbly oscila com baixo atrito, config.stiff é rápida e responsiva, e config.slow é muito gradual. Importe-as de react-spring.

Os valores retornados por useSpring são objetos SpringValue, não números comuns. Não é possível renderizá-los diretamente em JSX nem usá-los em objetos de estilo comuns. Eles precisam ser aplicados a componentes animated.* que sabem como se inscrever nas atualizações das molas e aplicá-las ao DOM com eficiência.

Passar immediate: true para useSpring faz com que os valores saltem instantaneamente para o destino, ignorando a animação da mola. Isso é útil na renderização inicial, quando o usuário ativou "reduzir movimento" nas configurações do OS, ou quando é necessário redefinir a posição por meio de código sem qualquer movimento visual.

É possível inverter uma animação de mola alternando quais valores são usados como origem e destino em from e to. Um padrão comum é armazenar o estado de uma alternância booleana e calcular a origem e o destino com base nele: quando a alternância é falsa, a animação vai de 0 a 1; quando é verdadeira, vai de 1 a 0. O react-spring faz a transição entre os estados suavemente.

useSpring pode retornar uma matriz com dois elementos: const [springs, api] = useSpring(() => ({ from: { x: 0 } })). O objeto api oferece controle programático. Chame api.start({ x: 100 }) para animar até um novo valor, api.stop() para congelar a animação e api.set({ x: 50 }) para saltar até o valor sem animação.

Use a forma declarativa useSpring({ from, to }) quando a animação depender do estado do React que muda normalmente. Use a forma imperativa com api.start() quando precisar disparar animações a partir de manipuladores de eventos, gestos ou operações assíncronas sem causar novas renderizações do React.

useSpring aceita funções de retorno do ciclo de vida em sua configuração. onStart é executado quando a mola começa a animar. onChange é executado a cada quadro com o valor atual — útil para efeitos colaterais que acompanham a posição. onRest é executado quando a mola se estabiliza em seu valor final, indicando que a animação foi concluída.

Na forma declarativa, useSpring executa automaticamente a animação novamente quando os valores passados a ele mudam. Por exemplo, useSpring({ opacity: isVisible ? 1 : 0 }) animará a opacidade sempre que isVisible mudar. Essa é a forma mais simples de vincular animações de mola ao estado do componente.

Na configuração do react-spring, o que tensão e atrito controlam?

O react-spring anima usando física: tensão (rigidez), atrito (amortecimento) e massa definem o movimento. useSpring({ from, to }) retorna objetos SpringValue aplicados a componentes animated.*. Configurações predefinidas (suave, oscilante, rígida, lenta) abrangem casos comuns. A API imperativa [springs, api] permite controle programático por meio de api.start(), api.stop() e api.set(). onRest é executado quando a animação se estabiliza.