loadingaicon

Drop-in React component for transparent AI-generated loading animations (WebM with alpha).

Install

npm install loadingaicon

Usage

import { LoadingIcon } from "loadingaicon";

function App() {
  return (
    <LoadingIcon
      src="/animations/jellyfish-transparent.webm"
      width={200}
      height={200}
    />
  );
}

Next.js (App Router)

Works out of the box — the component is SSR-safe and hydrates on the client.

// app/loading.tsx
import { LoadingIcon } from "loadingaicon";

export default function Loading() {
  return (
    <div style={{ display: "flex", justifyContent: "center", padding: 80 }}>
      <LoadingIcon src="/animations/spinner.webm" width={160} height={160} />
    </div>
  );
}

Safari Fallback

Safari doesn't support WebM with alpha. Provide a fallback prop (GIF, APNG, or static image):

<LoadingIcon
  src="/animations/spinner.webm"
  fallback="/animations/spinner.gif"
  width={120}
  height={120}
/>

If no fallback is provided, a minimal CSS spinner renders automatically.

Customization

<LoadingIcon
  src="/animations/spinner.webm"
  width={200}
  height={200}
  speed={1.5}
  borderRadius={16}
  background="rgba(0,0,0,0.05)"
  opacity={0.9}
  filter="hue-rotate(90deg)"
  objectFit="cover"
  loop={false}
  onEnd={() => console.log("done")}
  onClick={() => console.log("clicked")}
/>

Props

| Prop | Type | Default | Description | | -------------- | --------------------------------- | ----------- | -------------------------------------------------- | | src | string | (required) | URL to the transparent .webm video | | fallback | string | — | Fallback image URL for non-WebM browsers | | width | number \| string | 120 | Width in px or CSS value | | height | number \| string | 120 | Height in px or CSS value | | className | string | — | CSS class on the container | | style | CSSProperties | — | Inline styles on the container | | alt | string | "Loading" | Accessible label (aria-label) | | speed | number | 1 | Playback speed (0.5 = half, 2 = double) | | paused | boolean | false | Pause the animation | | loop | boolean | true | Whether the animation loops | | objectFit | "contain" \| "cover" \| "fill" | "contain" | How the video fits the container | | borderRadius | number \| string | — | Border radius on the container | | background | string | — | Background color/value on the container | | opacity | number | — | Opacity of the container (0–1) | | filter | string | — | CSS filter on the video ("grayscale(1)", etc.) | | onClick | MouseEventHandler | — | Click handler on the container | | onLoop | () => void | — | Fires each time the animation loops (loop=true) | | onEnd | () => void | — | Fires when the animation ends (loop=false) |

Exports

// Component
import { LoadingIcon } from "loadingaicon";

// Hook — check if current browser supports WebM alpha
import { useWebmSupport } from "loadingaicon";

// Types
import type { LoadingIconProps } from "loadingaicon";