react-anim-fast

Lightweight CSS-driven UI animations with a small React helper API.

Install

npm install react-anim-fast

Import the CSS once in your app entry:

import "react-anim-fast/styles.css";

Then use the React helpers or the exported class maps:

import { Animated, CONTINUOUS, ONE_SHOTS, animationClassName } from "react-anim-fast";

export function Example({ saving }: { saving: boolean }) {
  return (
    <>
      <Animated as="span" loop="spin" aria-hidden>
        *
      </Animated>

      <Animated oneShot="fadeInUp" trigger={saving}>
        Saved
      </Animated>

      <div className={CONTINUOUS.pulse}>Live</div>
      <div className={ONE_SHOTS.flash}>Highlighted once on mount</div>
      <div className={animationClassName({ className: "badge", loop: "blink" })}>
        Alert
      </div>
    </>
  );
}

Animation Catalog

One-shot animations:

| Name | Class | | --- | --- | | shake | anim-shake | | blink | anim-blink | | flash | anim-flash | | fadeIn | anim-fade-in | | fadeInUp | anim-fade-in-up | | fadeInDown | anim-fade-in-down | | fadeInLeft | anim-fade-in-left | | fadeInRight | anim-fade-in-right | | fadeOut | anim-fade-out | | fadeOutUp | anim-fade-out-up | | fadeOutDown | anim-fade-out-down | | fadeOutLeft | anim-fade-out-left | | fadeOutRight | anim-fade-out-right |

Continuous animations:

| Name | Class | | --- | --- | | spin | anim-spin | | marquee | anim-marquee | | marqueeReverse | anim-marquee-reverse | | blink | anim-blink-loop | | pulse | anim-pulse | | glow | anim-banner-glow |

Helper classes:

| Name | Class | | --- | --- | | marqueeViewport | anim-marquee-viewport |

For non-React usage, use the maps directly or animationClassName:

import { animationClassName } from "react-anim-fast";

const className = animationClassName({
  className: "status",
  oneShot: "fadeInRight",
  loop: "pulse",
});

React API

Animated renders a DOM element, merges animation classes with your className, and replays one-shot animations whenever trigger becomes truthy.

<Animated as="button" oneShot="blink" trigger={errorCount}>
  Retry
</Animated>

<Animated as="span" loop="pulse">
  Recording
</Animated>

For fade-out exit flows, keep the class on the element until you unmount it:

<Animated
  oneShot="fadeOutLeft"
  trigger={closing}
  persistOneShotClass
  onAnimationEnd={() => setMounted(false)}
>
  Closing panel
</Animated>

useOneShot is available when you need to attach the replay behavior to your own component.

import { useEffect } from "react";
import { useOneShot } from "react-anim-fast";

function SaveButton({ saved }: { saved: boolean }) {
  const { ref, trigger, className } = useOneShot<HTMLButtonElement>();

  useEffect(() => {
    if (saved) trigger("flash");
  }, [saved, trigger]);

  return (
    <button ref={ref} className={className}>
      Save
    </button>
  );
}

Marquee

Wrap marquee content in anim-marquee-viewport so overflowing text is clipped:

import { CONTINUOUS, HELPERS } from "react-anim-fast";

<div className={HELPERS.marqueeViewport}>
  <span className={CONTINUOUS.marquee}>System status updates</span>
</div>;

Tuning

The CSS uses custom properties so animations can be tuned per element:

import type { CSSProperties } from "react";

<Animated
  loop="spin"
  style={{
    "--anim-duration": "700ms",
    "--anim-origin": "center",
  } as CSSProperties}
>
  *
</Animated>

Common variables:

| Variable | Default | | --- | --- | | --anim-duration | depends on animation | | --anim-delay | 0s | | --anim-easing | depends on animation | | --anim-distance | 1rem | | --anim-scale | 1.04 | | --anim-min-opacity | 0.18 | | --anim-marquee-start | 100% | | --anim-marquee-end | -100% |

Directional fade names follow common UI semantics: fadeInLeft enters from the left, while fadeOutLeft exits toward the left.