Documentação

Documentação

O useAnimations é uma biblioteca gratuita, com licença MIT, de 300 ícones animados para React. Cada ícone já vem com uma interação: fica em loop, toca no clique ou toca no hover. Use os ícones com o pacote react-useanimations ou adicione-os com a CLI do shadcn.

Primeiros passos

npm install react-useanimations

import UseAnimations from 'react-useanimations';
import github from 'react-useanimations/lib/github';

export default function Header() {
  return <UseAnimations animation={github} size={32} />;
}

O ícone segue a cor do texto e executa a própria interação: o github fica em loop enquanto o mouse está sobre ele. O pacote não tem dependências; um player embutido (8 kB com gzip) desenha os ícones em SVG, e cada ícone é um módulo separado, então o seu bundle inclui só os ícones que você importa.

Interações

Cada ícone vem com a interação para a qual foi desenhado. Para trocá-la, use a prop interaction.

Quando o usuário prefere movimento reduzido, os ícones ficam parados: os loops mostram o primeiro frame, as animações de hover e de replay não tocam, e os toggles passam para o novo estado na hora.

Props

<UseAnimations animation={github} size={56} strokeColor="#4b5cff" style={{ padding: 8 }} />

Qualquer outra prop (className, aria-label, onClick, …) vai para o <span> que envolve o ícone. Os seus event handlers rodam antes dos da animação; chame event.preventDefault() para pular a animação.

Como importar os ícones

Importe cada ícone de react-useanimations/lib/<name>, ou vários de uma vez de react-useanimations/icons:

import { github, heart, menu } from 'react-useanimations/icons';

Nos dois casos, os builds de produção incluem só os ícones que você usa. Servidores de desenvolvimento e test runners não fazem tree-shaking, então neles react-useanimations/icons carrega todos os ícones; se isso fizer diferença, prefira lib/<name>. delete e package são palavras reservadas: importe-os como deleteIcon e packageIcon.

Toggle controlado

import { useState } from 'react';
import UseAnimations from 'react-useanimations';
import menu from 'react-useanimations/lib/menu';

export function MenuButton() {
  const [open, setOpen] = useState(false);
  return (
    <UseAnimations
      animation={menu}
      size={40}
      active={open} // também anima quando `open` muda em outro lugar
      onClick={() => setOpen(!open)}
    />
  );
}

Coloque o ícone num botão de verdade

Para ícones clicáveis, envolva o ícone num elemento focável usando a prop render: os eventProps vão no seu elemento e os animationProps num <span> dentro dele. Assim, as animações de hover também tocam quando o botão recebe foco pelo teclado.

import heart from 'react-useanimations/lib/heart';

<UseAnimations
  animation={heart}
  size={32}
  render={(eventProps, animationProps) => (
    <button type="button" aria-label="Add to favorites" {...eventProps}>
      <span {...animationProps} />
    </button>
  )}
/>;

Tamanho e cor

Os ícones são ícones de linha desenhados numa prancheta de 24 ou 32 px e continuam nítidos em qualquer tamanho: defina size com um número de pixels ou qualquer medida CSS.

Os traços seguem currentColor, então os ícones assumem sozinhos a cor do texto, os estados de hover e o modo escuro. Mude as cores com strokeColor e fillColor, com a propriedade CSS color ou estilizando os paths: a regra embutida tem especificidade zero, então o seu CSS sempre prevalece.

Alguns ícones têm um recorte vazado (a barra em visibility, microphone, video, volume e notification, o check em download, o anel em volta do badge de notification3). Esse vão assume a cor de fundo da página: branco em páginas claras e escuro em páginas com color-scheme: dark. Em outros fundos, defina a cor com a variável CSS --ua-knockout, por exemplo body { --ua-knockout: #0f172a; }.

// Tailwind: cor e espessura do traço
<UseAnimations animation={github} className="text-indigo-500 [&_path]:stroke-[3]" />

Next.js e renderização no servidor

O componente é marcado com 'use client' e desenha a animação só no navegador, então você pode renderizá-lo a partir de server components e de frameworks com SSR (Next.js, Remix, Astro) sem dynamic(…, { ssr: false }). Os módulos dos ícones são dados simples, então os server components podem importá-los e passá-los como props.

shadcn/ui

Todos os ícones também estão num registry do shadcn. A CLI adiciona um componente pronto e instala o react-useanimations:

npx shadcn@latest add https://useanimations.com/r/checkmark.json

import { AnimatedCheckmark } from '@/components/animations/checkmark';

<AnimatedCheckmark size={24} />;

O componente se chama Animated + o id do ícone em PascalCase (check-box → AnimatedCheckBox), vai para components/animations/<id>.tsx e recebe as mesmas props que o UseAnimations. O índice do registry fica em /r/registry.json. Para usar a forma curta npx shadcn@latest add @useanimations/checkmark, adicione o registry ao components.json:

{
  "registries": {
    "@useanimations": "https://useanimations.com/r/{name}.json"
  }
}

Sua própria animação

import animationData from './my-animation.json';

<UseAnimations animation={{ animationData, interaction: 'hover' }} />;

A sua animação precisa ser um arquivo Lottie JSON, o mesmo formato dos ícones. O player suporta o que os ícones precisam: shape layers, precomposições, null layers e parenting, paths, retângulos, elipses, traços, preenchimentos, trim paths, máscaras, keyframes com easing, holds e motion paths, e as expressões loopOut() e wiggle(). O resto, como gradientes, camadas de texto ou de imagem, efeitos e mattes, não é desenhado; o console avisa sobre camadas, formas e expressões não suportadas.

Arquivos e icons.json

Todos os ícones também podem ser baixados, na página de cada um (em inglês) ou em URLs estáveis com CORS habilitado:

O icons.json lista cada ícone com id, título, categoria, palavras-chave de busca, interação, URLs dos arquivos, tamanho e duração, o import do react-useanimations e o comando do shadcn. O pacote npm traz os mesmos dados: react-useanimations/catalog.json (metadados), react-useanimations/icons (as animações) e react-useanimations/svg.json (os SVGs estáticos).

Uso sem React

Os ícones são Lottie JSON padrão, então qualquer player Lottie consegue tocá-los a partir de https://useanimations.com/icons/<id>.json ou de uma cópia no seu projeto. Fora do React, a interação fica por sua conta. A página Ícones Lottie tem mais players e exemplos.

Alguns ícones usam expressões do After Effects (loopOut(), wiggle()); o campo requiresFullPlayer os identifica no icons.json. Na web, eles precisam do build completo do lottie-web, não do lottie_light, e os players nativos não avaliam expressões.

HTML e JavaScript

<div id="icon" style="width: 48px; height: 48px"></div>

<script src="https://cdn.jsdelivr.net/npm/lottie-web@5.13.0/build/player/lottie.min.js"></script>
<script>
  const el = document.getElementById('icon');
  const animation = lottie.loadAnimation({
    container: el,
    renderer: 'svg',
    loop: false,
    autoplay: false,
    path: 'https://useanimations.com/icons/archive.json',
  });
  // hover: para a frente ao entrar, ao contrário ao sair
  el.addEventListener('mouseenter', () => {
    animation.setDirection(1);
    animation.play();
  });
  el.addEventListener('mouseleave', () => {
    animation.setDirection(-1);
    animation.play();
  });
</script>

Com o renderer SVG, o ícone pode seguir a cor do texto, como no componente React:

#icon path[stroke^='rgb']:not([stroke='rgb(255,255,255)']) {
  stroke: currentColor;
}
#icon path[fill='rgb(0,0,0)'] {
  fill: currentColor;
}

Vue

<script setup>
import lottie from 'lottie-web';
import { onBeforeUnmount, onMounted, ref } from 'vue';

const el = ref(null);
let animation;
onMounted(() => {
  animation = lottie.loadAnimation({
    container: el.value,
    renderer: 'svg',
    loop: true,
    autoplay: true,
    path: 'https://useanimations.com/icons/loading.json',
  });
});
onBeforeUnmount(() => animation?.destroy());
</script>

<template>
  <div ref="el" style="width: 48px; height: 48px" />
</template>

React Native

import LottieView from 'lottie-react-native';

<LottieView source={require('./loading.json')} autoPlay loop style={{ width: 48, height: 48 }} />;

iOS

Com o lottie-ios e o JSON no bundle do app:

import Lottie
import SwiftUI

LottieView(animation: .named("loading"))
  .looping()
  .frame(width: 48, height: 48)

Android

Com o lottie-android no Jetpack Compose e o JSON em res/raw:

val composition by rememberLottieComposition(LottieCompositionSpec.RawRes(R.raw.loading))
LottieAnimation(composition, iterations = LottieConstants.IterateForever, modifier = Modifier.size(48.dp))

Flutter

Com o pacote lottie:

Lottie.asset('assets/loading.json', width: 48, height: 48)

Desempenho e acessibilidade

• Leve: o player tem 8 kB com gzip e nenhuma dependência, e um ícone tem de 1 a 15 kB (mediana de 2 kB).
• Sob demanda: as animações só são desenhadas no navegador, depois que a página renderiza; loops com autoplay pausam enquanto estão fora da área visível, e tudo é liberado no unmount.
• Decorativos por padrão: os ícones ficam ocultos para leitores de tela (aria-hidden), a menos que você passe aria-label, o que faz o ícone ser anunciado como imagem. Para controles que têm só um ícone, use um <button> de verdade com aria-label (veja acima) e indique o estado do toggle com aria-pressed ou aria-expanded.
• Movimento reduzido e toque: os ícones respeitam prefers-reduced-motion, e toques em telas sensíveis ao toque não disparam animações de hover.

Agentes de código com IA

Os agentes podem escolher ícones por palavra-chave ou por interação no icons.json, ou no react-useanimations/catalog.json dentro do pacote, e usar a linha de import ou o comando do shadcn que ele informa. As definições de tipo de cada import de ícone também trazem título, palavras-chave, interação e prévia. Esta documentação está disponível em Markdown em /documentation.md, e o /llms.txt indexa o site.

Atualizando da v2

Para a maioria dos apps, atualizar significa instalar a v3: o componente, os imports react-useanimations/lib/<name> e todos os 79 ícones da v2 continuam iguais. Siga os passos abaixo que se aplicam ao seu código.

1. Instale a v3

A v3 exige React 18 ou mais recente e não tem dependências. Remova também o lottie-web, a menos que outra parte do seu app o use.

npm install react-useanimations@3
npm uninstall lottie-web

2. Troque reverse por active

active é totalmente controlada: o ícone anima quando active muda, e um clique sozinho não o alterna, então atualize o valor no onClick. reverse continua funcionando como na v2 (define o estado inicial, e os cliques alternam o ícone), mas está obsoleta. As duas valem só para ícones click-toggle: os quatro círculos com seta agora tocam de novo a cada clique (veja o passo 6).

- <UseAnimations animation={checkBox} reverse={checked} onClick={toggle} />
+ <UseAnimations animation={checkBox} active={checked} onClick={toggle} />

3. Confira as cores

Na v2, os ícones eram pretos, a menos que você definisse strokeColor. Na v3, os ícones seguem a cor do texto (currentColor), e fillColor usa strokeColor como padrão. Ícones dentro de texto colorido ou de links mudam de cor junto; para mantê-los pretos, defina a cor você mesmo:

<UseAnimations animation={github} strokeColor="#000" />

4. Substitua wrapperStyle, pathCss e options

• wrapperStyle está obsoleta: use style.
• pathCss foi removida: estilize os paths com uma classe.
• options (configurações do lottie-web) foi removida junto com o lottie-web. Use as props loop, autoplay e speed; as outras opções do lottie-web não têm equivalente.

Se você passar pathCss ou options mesmo assim, um aviso aparece uma vez no console, e elas são ignoradas.

- <UseAnimations animation={github} wrapperStyle={{ margin: 8 }} pathCss="stroke-width: 3px;" options={{ loop: true }} />
+ <UseAnimations animation={github} style={{ margin: 8 }} className="thick" loop />

.thick path {
  stroke-width: 3px;
}

5. Confira o elemento wrapper

O wrapper agora é um <span> inline-block em vez de uma <div>, então ele é válido dentro de botões e links e fica alinhado à linha do texto. Atualize o CSS que mira o wrapper como div e aplique os animationProps num <span> na prop render:

  render={(eventProps, animationProps) => (
    <button type="button" aria-label="Like" {...eventProps}>
-     <div {...animationProps} />
+     <span {...animationProps} />
    </button>
  )}

Agora os ícones ficam ocultos para leitores de tela (aria-hidden), a menos que você passe aria-label; adicione um aos ícones que transmitem significado sozinhos.

6. Confira os ícones cuja interação mudou

As interações agora são as mesmas de useanimations.com. Se um ícone deve se comportar como na v2, passe a interação antiga:

* Na v2, esses ícones tocavam uma vez quando o mouse entrava e pulavam de volta para o início quando ele saía; hover-replay é o mais próximo disso.

<UseAnimations animation={zoomIn} interaction="loop" />

7. Atualize os imports

Importe os ícones só como react-useanimations/lib/<name> ou de react-useanimations/icons. Os caminhos internos de arquivos da v2, como react-useanimations/lib/github/index ou react-useanimations/lib/github/github.json, não são mais resolvidos; o Lottie JSON é o animationData do ícone:

- import githubJson from 'react-useanimations/lib/github/github.json';
+ import github from 'react-useanimations/lib/github';
+ const githubJson = github.animationData;

Os caminhos react-useanimations/utils foram removidos. Importe os tipos do próprio pacote:

- import type { Animation, AnimationKey } from 'react-useanimations/utils';
+ import type { Animation, AnimationKey, Interaction, UseAnimationsProps } from 'react-useanimations';

Animation agora é { animationData, interaction }; o campo animationKey da v2 deixou de existir, então objetos que você montou por conta própria passam a usar interaction.

O que mais há de novo

221 ícones a mais (300 no total), vários ícones de uma vez a partir de react-useanimations/icons, suporte a movimento reduzido, hover no foco pelo teclado, nada de animações de hover travadas em telas sensíveis ao toque, renderização no servidor sem workarounds e um registry do shadcn.

Licença

Os ícones e o código são distribuídos sob a licença MIT: você pode usar, modificar e redistribuir em trabalhos pessoais e comerciais. A atribuição não é obrigatória, mas é bem-vinda:

Animated icons by <a href="https://useanimations.com">useAnimations</a>

Termos completos: Licença e termos.

Perguntas frequentes