cli-loaders for react

Animated braille-glyph loading spinners for React. 19 unique animations, zero dependencies, fully accessible. — Live demo → · GitHub →

cli-loaders gives you 19 animated braille-glyph spinners as a set of composable, accessible React components. Zero runtime dependencies beyond React itself.

Features

• 19 spinner animations with unique braille Unicode patterns
• Zero runtime dependencies — pure React, no external libraries
• Fully accessible — WCAG 2.1 AA, prefers-reduced-motion support, semantic HTML
• TypeScript first — complete type definitions, DotShape export for custom rendering
• Composable — 7 components + 2 hooks for any use case
• Small bundle — ~15KB gzipped (lib) + optional SVG rendering
• Shape customization — render as circles, squares, or diamonds (SVG mode)

Why cli-loaders?

vs. react-spinners: Smaller bundle, braille Unicode art for terminal-like aesthetics, context API for global defaults, shape customization (circles/squares/diamonds)

vs. react-loading: Zero dependencies, comprehensive accessibility testing, 19+ unique animations, SVG rendering mode

vs. custom CSS: No @keyframes to maintain, out-of-the-box reduced-motion support, semantic HTML, accessible by default

Install

npm install @agilek/cli-loaders
# or
pnpm add @agilek/cli-loaders
# or
yarn add @agilek/cli-loaders

Requires React ≥ 18.

Quick start

import { Spinner } from '@agilek/cli-loaders';

// Minimal — defaults to the "braille" spinner
<Spinner />

// Named + coloured
<Spinner name="helix" color="#7c3aed" size="1.5rem" />

// With custom dot shape (renders as SVG instead of braille text)
<Spinner name="scan" color="#00ff99" shape="square" size="2rem" />

Components

<Spinner>

The base animated glyph. Renders as an inline <span> so it drops naturally into any line of text.

Any additional HTML span attributes are forwarded.

<SpinnerInline>

Spinner + children in a flex row — handy for inline status messages.

<SpinnerInline name="braille" color="#00ff99">
  Fetching data…
</SpinnerInline>

Accepts all Spinner props plus:

<SpinnerText>

Decorates a text string with spinners — supports a bookend mode that mirrors one on each end.

<SpinnerText text="Deploying" color="#f59e0b" bookend />
// ⠿ Deploying ⠿

Plus all Spinner props.

<SpinnerBadge>

A tinted pill badge with a spinner — good for live status indicators.

<SpinnerBadge label="Live"     color="#ef4444" />
<SpinnerBadge label="Syncing"  color="#38bdf8" />
<SpinnerBadge label="Building" color="#f59e0b" />

Plus all Spinner props.

<SpinnerTrail>

Renders a sliding window of recent frames with decreasing opacity — creates a ghost/motion-blur trail effect.

<SpinnerTrail name="helix" color="#7c3aed" size="2rem" trailLength={6} />

Plus all Spinner props.

<SpinnerButton>

A <button> with a built-in loading state. Disables itself and shows a spinner when loading is true. Fully forwarded ref.

<SpinnerButton
  loading={isSaving}
  onClick={handleSave}
  spinnerProps={{ name: 'braille', color: '#00ff99' }}
>
  Save changes
</SpinnerButton>

All standard <button> attributes are forwarded.

<SpinnerOverlay>

Wraps any content and renders a centered spinner overlay when active. Uses the native inert attribute to block keyboard/pointer access to the content beneath.

<SpinnerOverlay
  active={isLoading}
  name="orbit"
  color="#7c3aed"
  size="2.5rem"
  backdrop="rgba(0,0,0,0.4)"
>
  <YourContent />
</SpinnerOverlay>

Plus all Spinner props.

<SpinnerProvider>

Sets global defaults for every Spinner-family component in the subtree. Individual props override context values.

<SpinnerProvider
  defaultName="orbit"
  defaultColor="#7c3aed"
  defaultSpeed={1.2}
  respectReducedMotion={true}
>
  <App />
</SpinnerProvider>

// Inside: no props needed — picks up context defaults
<Spinner />
<SpinnerBadge label="Live" />

useSpinner hook

Drive any element with the raw frame string for fully custom rendering.

import { useSpinner } from 'cli-loaders';

function MyComponent() {
  const frame = useSpinner('helix', 1.5);

  return (
    <h1 style={{ fontFamily: 'monospace', color: '#00ff99' }}>
      {frame}
    </h1>
  );
}

useSpinner(
  name: SpinnerName,
  speed?: number,           // default 1
  paused?: boolean,         // default false
  ignoreReducedMotion?: boolean  // default false
): string

useSpinnerFrames

Returns a sliding window of the last length frames — the primitive behind SpinnerTrail.

useSpinnerFrames(
  name: SpinnerName,
  length?: number,          // default 3
  speed?: number,
  paused?: boolean,
  ignoreReducedMotion?: boolean
): string[]

Available spinners

All 19 names are available as the SpinnerName union type.

import { spinnerNames } from 'cli-loaders';
// ['braille', 'braillewave', 'dna', ...]

Accessibility

• The animated glyph is wrapped in aria-hidden="true" — it is invisible to screen readers.
• A visually-hidden <span role="status" aria-live="polite"> announces the label prop (default: "Loading").
• SpinnerButton sets aria-busy and aria-disabled on the button element automatically.
• SpinnerOverlay sets aria-busy on the container and uses the native inert attribute to prevent keyboard/AT access to obscured content.
• By default, all animations respect prefers-reduced-motion: reduce. Override per-component with ignoreReducedMotion or globally via <SpinnerProvider respectReducedMotion={false}>.

FAQ

Can I use this with Next.js? Yes. Works as both client and server components in the App Router.

How do I customize spinner animations? Use the useSpinner hook to drive any custom rendering. See useSpinner hook for examples.

Does this work with TypeScript? Full type support. All component props and the DotShape type are exported for type safety.

How do I change shapes (circles, squares, diamonds)? Use the shape prop: <Spinner shape="square" />. See Spinner props for details.

Does this support reduced motion preferences? Yes, by default. Animations pause when prefers-reduced-motion: reduce is set. Override with ignoreReducedMotion={true}.

What's the bundle size? ~15KB gzipped for the core library. SVG rendering mode adds ~1KB.

Common Patterns

Form submission with loading state

const [loading, setLoading] = useState(false);

async function handleSubmit() {
  setLoading(true);
  try {
    await api.post('/submit', data);
  } finally {
    setLoading(false);
  }
}

return (
  <SpinnerButton
    loading={loading}
    onClick={handleSubmit}
    spinnerProps={{ name: 'helix', color: '#00ff99' }}
  >
    {loading ? 'Submitting...' : 'Submit'}
  </SpinnerButton>
);

Full-screen loading overlay

const [fetching, setFetching] = useState(false);

return (
  <SpinnerOverlay
    active={fetching}
    name="orbit"
    size="2rem"
    backdrop="rgba(0,0,0,0.5)"
  >
    <Dashboard data={data} />
  </SpinnerOverlay>
);

Inline status message with shape customization

return (
  <SpinnerInline
    name="scan"
    shape="diamond"
    color="#7c3aed"
  >
    Syncing your data...
  </SpinnerInline>
);

Contributing

Bug reports and pull requests are welcome. Please open an issue before submitting large changes.

# Install dependencies
npm install

# Start the interactive demo
npm run dev

# Build the library
npm run build

License

MIT