tinygrid

Animated 3×3 grid loaders for React. Sixteen single-color choreographies, fully themeable, zero runtime dependencies.

import { TinyGrid } from '@karthikmudunuri/tinygrid';

<TinyGrid variant="wave" color="#22d3ee" />

Install

npm install @karthikmudunuri/tinygrid
# or
pnpm add @karthikmudunuri/tinygrid
# or
yarn add @karthikmudunuri/tinygrid

Requires React 18 or newer.

Usage

The component is a single default export with four optional props.

import { TinyGrid } from '@karthikmudunuri/tinygrid';

export function LoadingState() {
  return <TinyGrid variant="spiral" color="oklch(70% 0.18 280)" cellSize={10} />;
}

Props

| Prop | Type | Default | Description | |---|---|---|---| | variant | TinyGridVariant | 'wave' | Which animation to play. See all 16 below. | | color | string | '#22d3ee' | Any valid CSS color. Hex, rgb, oklch, or a CSS variable. | | cellSize | number | 8 | Size of each cell in pixels. | | gap | number | 2 | Gap between cells in pixels. | | className | string | undefined | Applied to the outer grid container. |

Variants

| Variant | Motion | |---|---| | wave | Left-to-right sweep. | | waveReverse | Right-to-left sweep. | | waveDown | Top-to-bottom cascade. | | waveUp | Bottom-to-top rise. | | spiral | Clockwise spiral from corner. | | corners | Corners light first, then centre. | | radial | Centre-out ripple. | | diagonal | Top-left diagonal band. | | snake | Boustrophedon path. | | cross | Plus-sign emphasis. | | checker | Alternating checkerboard. | | rain | Random scatter. | | pinwheel | Rotating blades. | | orbit | Outer-ring chase. | | converge | Edges inward to centre. | | zigzag | Angular alternating path. |

Color

Any CSS color string works. The off-state cells use the same hue at reduced opacity, so the loader tints cleanly against both light and dark backgrounds.

<TinyGrid color="#22d3ee" />             {/* hex */}
<TinyGrid color="oklch(70% 0.18 280)" /> {/* oklch */}
<TinyGrid color="var(--accent)" />       {/* css variable */}

Accessibility

The component is aria-hidden by default (it's purely decorative). It respects the user's prefers-reduced-motion setting — if reduced motion is requested, all cells remain illuminated without animation.

Programmatic access

If you need the variant list or preset timings:

import {
  TINYGRID_VARIANTS,
  TINYGRID_PRESETS,
  type TinyGridVariant,
  type TinyGridPreset,
} from '@karthikmudunuri/tinygrid';

TINYGRID_VARIANTS.map((name) => <TinyGrid key={name} variant={name} />);
TINYGRID_PRESETS.spiral; // { delays, duration, label, description }

Credits

The nine-cell timing choreography is adapted from MetaHeavies/3-pixel-grid (MIT). TinyGrid is a React/TypeScript rewrite with an opacity-based render model and a single-prop API.

License

MIT