Gridora

Animated grid loaders for React. Motion variants, per-dot effects, shapes, color ramps, and a built-in bitmap font for text loaders.

Install the published package from npm, or clone this repository to run the live editor and explore the full source.

Highlights

• 130+ variants across sequential, radial, cascade, flow, wipe, decrypt, letters, digits, symbols, and more
• 20 effects (pulse, bounce, glow, spin, …) and 12 dot shapes (circle, diamond, star, …)
• Color ramps with horizontal, radial, angular, and other sampling modes
• Resolution-independent: the same variant scales cleanly from 2×2 to 12×12
• CSS-driven animation: keyframes injected on import (optional static gridora/styles.css)
• Accessible: role="status", optional labels, and respectReducedMotion
• Tree-shakeable ESM + CJS build with full TypeScript types

Install

pnpm add gridora
# or
npm install gridora
# or
bun add gridora

Peer dependency: React 18+.

Usage

Import the component — keyframe styles are injected automatically on the client:

import { GridLoader } from "gridora"

export function Loader() {
  return <GridLoader variant="orbit" />
}

Optional: import gridora/styles.css yourself if you prefer a static stylesheet (SSR without flash, strict CSP, etc.).

Customization

<GridLoader
  variant="radialPulse"
  gridSize={7}
  cellSize={6}
  gap={2}
  speed={1.2}
  colors={["#6366f1", "#a855f7", "#ec4899"]}
  colorMode="radial"
  effect="glow"
  shape="diamond"
  glow={4}
/>

Text loader

Draw arbitrary strings with the built-in bitmap font:

import { GridLoaderText } from "gridora"

<GridLoaderText text="LOAD" effect="pulse" color="#fff" />

Live editor

Browse every variant, tune props, or paint a custom sequence:

• Gallery: gridora.gabrielayer.com/loaders/radial
• Studio: gridora.gabrielayer.com/studio

What's in this repository

This is a pnpm monorepo that ships two things:

Path	Description
packages/gridora	The publishable npm library (gridora)
src	Next.js website. Landing page, variant gallery, and interactive editor

The npm package contains only the compiled library (dist/). This GitHub repository includes the full source, the React components, variant registry, bitmap patterns, CSS keyframes, and the editor UI that powers the live playground.

gridora/
├── packages/gridora/     # library source → published to npm
│   ├── src/
│   │   ├── grid-loader.tsx
│   │   ├── variants.ts   # motion + glyph variant registry
│   │   ├── patterns.ts   # letter / digit / symbol bitmaps
│   │   ├── styles.ts     # effects, shapes, color helpers
│   │   └── grid-loader.css
│   └── tsup.config.ts
└── src/                  # Next.js app (uses workspace link to gridora)
    └── app/loaders/      # editor, gallery, code export

During local development the website imports the library directly from TypeScript source via the workspace link, no rebuild needed while iterating on components.

Development

Requirements: Node.js 20+, pnpm 10+

git clone https://github.com/0x65dgerunner/gridora.git
cd gridora
pnpm install

Run the website (editor + gallery)

pnpm dev

Open http://localhost:3000. The app transpiles gridora from source (transpilePackages in next.config.ts).

Build the website for production

pnpm build
pnpm start

Building the library

Compile the package into packages/gridora/dist/ (ESM, CJS, .d.ts, and bundled CSS):

pnpm build:lib

This runs tsup inside the workspace package:

• Entry: packages/gridora/src/index.ts
• Output: dist/index.js, dist/index.cjs, dist/index.d.ts, dist/styles.css
• Externals: react, react-dom (peer dependencies)

Watch mode while working on the library:

pnpm --filter gridora dev

Publishing to npm

From the repo root, after building:

pnpm build:lib
pnpm --filter gridora publish --access public

prepublishOnly runs the build automatically. Only dist/ is included in the published tarball (files field in package.json).

Package README for npm consumers: packages/gridora/README.md.

API overview

Components

Export	Description
GridLoader	Main grid loader
GridLoaderText	Animated text using the bitmap font

Common props (GridLoader)

Prop	Type	Default	Description
variant	GridLoaderVariant	"tokenStream"	Motion or glyph pattern
gridSize	number	5	Rows and columns (2–12)
cellSize	number	5	Cell size in pixels
dotSize	number	cellSize	Dot size in pixels
gap	number	3	Space between cells
speed	number	1.5	Cycle duration in seconds
color	string	"currentColor"	Base color
colors	string[]	—	Color ramp
colorMode	GridLoaderColorMode	"solid"	How colors map to the grid
effect	GridLoaderEffect	"pulse"	Per-dot keyframe animation
shape	GridLoaderShape	"circle"	Dot silhouette
sequence	number[]	—	Custom cell order; overrides variant
paused	boolean	false	Freeze the animation
label	string	—	Accessible status label
respectReducedMotion	boolean	true	Honor prefers-reduced-motion

See grid-loader.tsx for the full prop list (easing, glow, spread, offset, mask, inactive, …).

Low-level exports

The package also exports the variant registry, pattern utilities, and style constants for custom tooling:

import {
  GRID_LOADER_VARIANTS,
  GRID_LOADER_EFFECTS,
  GRID_LOADER_SHAPES,
  computePhases,
  findGlyph,
  getMask,
  sequenceToPhases,
} from "gridora"

Scripts

Command	Description
pnpm dev	Start the Next.js editor locally
pnpm build	Production build of the website
pnpm build:lib	Compile the npm package to packages/gridora/dist
pnpm start	Serve the production website
pnpm lint	Run ESLint

Links

• npm: gridora
• Editor: gridora.gabrielayer.com
• GitHub: 0x65dgerunner/gridora

License

MIT © 0x65dgerunner