Dokumentace

Dokumentace

useAnimations je bezplatná knihovna 300 animovaných ikon pro React pod licencí MIT. Každá ikona má vestavěnou interakci: běží ve smyčce, přehraje se po kliknutí nebo při najetí myší. Používat je můžete přes balíček react-useanimations, nebo si je přidat pomocí shadcn CLI.

Rychlý start

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

Ikona přebírá barvu textu a přehrává svou vlastní interakci: github běží ve smyčce, dokud je na ní kurzor. Balíček nemá žádné závislosti; ikony kreslí jako SVG vestavěný přehrávač (8 kB po gzipu) a každá ikona je samostatný modul, takže bundle obsahuje jen ikony, které naimportujete.

Interakce

Každá ikona má interakci, pro kterou byla navržena. Změníte ji propem interaction.

Když uživatel preferuje omezený pohyb, ikony zůstanou v klidu: smyčky ukážou svůj první snímek, animace při hoveru a po kliknutí se nepřehrají a přepínače přejdou do nového stavu okamžitě.

Props

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

Všechny ostatní props (className, aria-label, onClick, …) dostane obalový <span>. Vaše event handlery se spustí před handlery animace; voláním event.preventDefault() animaci přeskočíte.

Import ikon

Každou ikonu importujte z react-useanimations/lib/<name>, nebo jich naimportujte víc najednou z react-useanimations/icons:

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

Produkční build v obou případech obsahuje jen ikony, které používáte. Dev servery a test runnery ale tree-shaking nedělají, takže tam react-useanimations/icons načte všechny ikony; pokud vám na tom záleží, dejte přednost lib/<name>. delete a package jsou rezervovaná slova: importujte je jako deleteIcon a packageIcon.

Řízený přepínač

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} // animuje se i tehdy, když se `open` změní jinde
      onClick={() => setOpen(!open)}
    />
  );
}

Ikona ve skutečném tlačítku

U klikatelných ikon dejte kolem ikony pomocí propu render fokusovatelný prvek: eventProps patří na váš prvek a animationProps na <span> uvnitř něj. Animace na hover se pak přehrají i ve chvíli, kdy tlačítko získá fokus z klávesnice.

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

Velikost a barva

Ikony jsou lineární, nakreslené na plátně 24 nebo 32 px, a zůstanou ostré v jakékoli velikosti: size nastavte na počet pixelů nebo na libovolnou CSS délku.

Tahy používají currentColor, takže ikony samy převezmou barvu textu, hover stavy i tmavý režim. Barvu změníte pomocí strokeColor a fillColor, přes CSS color, nebo nastylujte přímo cesty (paths): vestavěné pravidlo má nulovou specificitu, takže vaše CSS vždy vyhraje.

Některé ikony mají v sobě vyříznutou mezeru (lomítko u visibility, microphone, video, volume a notification, fajfka u download, kroužek kolem odznaku u notification3). Mezera přebírá pozadí stránky: na světlých stránkách je bílá, na stránkách s color-scheme: dark tmavá. Pro jiná pozadí ji nastavte CSS proměnnou --ua-knockout, např. body { --ua-knockout: #0f172a; }.

// Tailwind: barva a tloušťka tahu
<UseAnimations animation={github} className="text-indigo-500 [&_path]:stroke-[3]" />

Next.js a vykreslování na serveru

Komponenta je označená 'use client' a animaci kreslí až v prohlížeči, takže ji můžete vykreslit ze server komponent i v SSR frameworcích (Next.js, Remix, Astro) bez dynamic(…, { ssr: false }). Moduly ikon jsou obyčejná data, takže je server komponenty mohou importovat a předávat jako props.

shadcn/ui

Všechny ikony jsou také v registru shadcn. CLI přidá hotovou komponentu a nainstaluje react-useanimations:

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

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

<AnimatedCheckmark size={24} />;

Komponenta se jmenuje Animated + id ikony v PascalCase (check-box → AnimatedCheckBox), uloží se do components/animations/<id>.tsx a přijímá stejné props jako UseAnimations. Index registru najdete na /r/registry.json. Pokud chcete používat krátký zápis npx shadcn@latest add @useanimations/checkmark, přidejte registr do components.json:

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

Vlastní animace

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

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

Vaše animace musí být Lottie JSON soubor, tedy stejný formát, jaký používají ikony. Přehrávač podporuje to, co ikony potřebují: tvarové vrstvy, prekompozice, null vrstvy a parenting, cesty, obdélníky, elipsy, tahy, výplně, trim paths, masky, klíčové snímky s easingem, hold klíčové snímky a pohybové cesty a výrazy (expressions) loopOut() a wiggle(). Nic dalšího, například přechody, textové a obrázkové vrstvy, efekty a matte, se nevykreslí; na nepodporované vrstvy, tvary a výrazy upozorní konzole.

Soubory a icons.json

Každou ikonu si můžete také stáhnout, a to z její stránky (v angličtině) nebo ze stálých URL s povoleným CORS:

icons.json obsahuje všechny ikony s jejich id, názvem, kategorií, klíčovými slovy pro hledání, interakcí, URL souborů, velikostí a délkou, importem z react-useanimations a příkazem pro shadcn. Stejná data obsahuje i npm balíček: react-useanimations/catalog.json (metadata), react-useanimations/icons (animace) a react-useanimations/svg.json (statická SVG).

Použití bez Reactu

Ikony jsou standardní Lottie JSON, takže je přehraje jakýkoli Lottie přehrávač, ať už z https://useanimations.com/icons/<id>.json, nebo z kopie ve vašem projektu. Mimo React si interakci musíte zapojit sami. Další přehrávače a příklady najdete na stránce Lottie ikony.

Některé ikony používají výrazy (expressions) z After Effects (loopOut(), wiggle()); v icons.json je označuje requiresFullPlayer. Na webu potřebují plný build lottie-web, ne lottie_light, a nativní přehrávače výrazy nevyhodnocují.

HTML a 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: dopředu při najetí, pozpátku při odjetí
  el.addEventListener('mouseenter', () => {
    animation.setDirection(1);
    animation.play();
  });
  el.addEventListener('mouseleave', () => {
    animation.setDirection(-1);
    animation.play();
  });
</script>

Se SVG rendererem může ikona přebírat barvu textu stejně jako React komponenta:

#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

S knihovnou lottie-ios a JSON souborem v bundlu aplikace:

import Lottie
import SwiftUI

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

Android

S knihovnou lottie-android v Jetpack Compose a JSON souborem v res/raw:

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

Flutter

S balíčkem lottie:

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

Výkon a přístupnost

• Malá velikost: přehrávač má po gzipu 8 kB a žádné závislosti, ikona má 1 až 15 kB (medián 2 kB).
• Líné vykreslování: animace se kreslí až v prohlížeči, po vykreslení stránky; automaticky spuštěné smyčky se pozastaví, když je odscrollujete mimo obrazovku, a při unmountu se vše uklidí.
• Ve výchozím stavu dekorativní: ikony jsou před čtečkami obrazovky skryté (aria-hidden), dokud nepředáte aria-label, se kterým je čtečka ohlásí jako obrázek. U ovládacích prvků, které obsahují jen ikonu, použijte skutečný <button> s aria-label (viz výše) a stav přepínače vyjádřete pomocí aria-pressed nebo aria-expanded.
• Omezený pohyb a dotyk: ikony respektují prefers-reduced-motion a klepnutí na dotykové obrazovce hover animace nespouštějí.

AI agenti pro programování

Agenti mohou vybírat ikony podle klíčového slova nebo interakce z icons.json, případně z react-useanimations/catalog.json uvnitř balíčku, a použít import nebo příkaz pro shadcn, který tam najdou. Typové definice každého importu ikony navíc obsahují její název, klíčová slova, interakci a náhled. Tato dokumentace je k dispozici také jako Markdown na /documentation.md (v angličtině) a /llms.txt obsahuje rejstřík celého webu.

Přechod z v2

Pro většinu aplikací znamená upgrade jen instalaci v3: komponenta, importy react-useanimations/lib/<name> i všech 79 ikon z v2 zůstávají stejné. Projděte kroky níže, které se týkají vašeho kódu.

1. Instalace v3

v3 vyžaduje React 18 nebo novější a nemá žádné závislosti. Odinstalujte i lottie-web, pokud ho ve vaší aplikaci nepoužívá nic jiného.

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

2. reverse nahraďte active

active je plně řízený: ikona se animuje, když se active změní, a samotné kliknutí ji nepřepne, takže hodnotu měňte v onClick. reverse funguje dál stejně jako ve v2 (nastaví počáteční stav a kliknutí ikonu přepínají), je ale zastaralý. Oba platí jen pro ikony click-toggle: čtyři šipky v kruhu se teď po kliknutí přehrají znovu (viz krok 6).

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

3. Zkontrolujte barvy

Ikony ve v2 byly černé, pokud jste nenastavili strokeColor. Ikony ve v3 přebírají barvu textu (currentColor) a fillColor má výchozí hodnotu strokeColor. Ikony uvnitř barevného textu nebo odkazů tak změní barvu spolu s nimi; pokud mají zůstat černé, nastavte barvu sami:

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

4. Nahraďte wrapperStyle, pathCss a options

• wrapperStyle je zastaralý: použijte style.
• pathCss byl odstraněn: cesty nastylujte pomocí třídy.
• options (nastavení lottie-web) zmizel spolu s lottie-web. Použijte props loop, autoplay a speed; ostatní volby lottie-web nemají náhradu.

Pokud pathCss nebo options přesto předáte, jednou se zaloguje varování a budou ignorovány.

- <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. Zkontrolujte obalový prvek

Obal je teď inline-block <span> místo <div>, takže je validní uvnitř tlačítek a odkazů a sedí na řádku textu. Upravte CSS, které cílí na obal jako na div, a v propu render rozbalte animationProps na <span>:

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

Ikony jsou teď před čtečkami obrazovky skryté (aria-hidden), dokud nepředáte aria-label; přidejte ho ikonám, které samy o sobě nesou význam.

6. Zkontrolujte ikony se změněnou interakcí

Interakce teď odpovídají webu useanimations.com. Pokud se má ikona chovat jako ve v2, předejte jí její původní interakci:

* Ve v2 se tyto ikony při najetí myší jednou přehrály a při odjetí skočily zpět na začátek; nejblíže tomu je hover-replay.

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

7. Aktualizujte importy

Ikony importujte jen jako react-useanimations/lib/<name> nebo z react-useanimations/icons. Interní cesty k souborům z v2, jako react-useanimations/lib/github/index nebo react-useanimations/lib/github/github.json, už nefungují; Lottie JSON najdete v animationData ikony:

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

Cesty react-useanimations/utils byly odstraněny. Typy importujte přímo z balíčku:

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

Animation je teď { animationData, interaction }; pole animationKey z v2 zmizelo, takže objekty, které si sestavujete sami, používají místo něj interaction.

Co je ještě nového

O 221 ikon víc (celkem 300), import více ikon najednou z react-useanimations/icons, podpora omezeného pohybu, hover při fokusu z klávesnice, žádné zaseknuté hover animace na dotykových obrazovkách, vykreslování na serveru bez obezliček a registr shadcn.

Licence

Ikony i kód jsou vydané pod licencí MIT: můžete je používat, upravovat a dále šířit v osobních i komerčních projektech. Uvedení autora není povinné, ale potěší nás:

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

Úplné podmínky: Licence a podmínky.

Časté dotazy