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.

| Prop | Type | Default | Description | |---|---|---|---| | name | SpinnerName | "braille" | Which spinner animation to use | | color | string | currentColor | CSS color value | | size | string \| number | undefined | Font size of the glyph, e.g. "1.5rem" or 24 | | speed | number | 1 | Playback multiplier — 2 = twice as fast | | paused | boolean | false | Freeze the animation | | ignoreReducedMotion | boolean | false | Override prefers-reduced-motion and always animate | | shape | "circle" \| "square" \| "diamond" | undefined | Render dots as SVG shapes instead of braille text | | label | string | "Loading" | Accessible label announced by screen readers | | className | string | — | Applied to the outer <span> | | style | CSSProperties | — | Inline styles for the outer <span> | | ref | Ref<HTMLSpanElement> | — | Forwarded to the outer <span> |

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:

| Prop | Type | Default | Description | |---|---|---|---| | gap | string \| number | "0.4em" | Gap between spinner and children | | children | ReactNode | — | Content rendered after the spinner |

<SpinnerText>

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

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

| Prop | Type | Default | Description | |---|---|---|---| | text | string | required | The text to decorate | | bookend | boolean | false | Place a spinner on both sides | | gap | string \| number | "0.4em" | Gap between spinners and text |

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" />

| Prop | Type | Default | Description | |---|---|---|---| | label | string | required | Badge text (also used as the a11y label) | | paddingY | string | "0.4em" | Vertical padding | | paddingX | string | "0.8em" | Horizontal base padding | | balanceRatio | number | 0.3 | Extra right padding fraction for optical balance | | borderRadius | string \| number | "999px" | Border radius | | gap | string \| number | "0.35em" | Gap between glyph and label |

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} />

| Prop | Type | Default | Description | |---|---|---|---| | trailLength | number | 4 | Number of ghost frames (including the current one) | | minOpacity | number | 0.1 | Opacity of the oldest ghost frame | | reverse | boolean | false | Flip the opacity gradient (bright on left, fading right) |

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>

| Prop | Type | Default | Description | |---|---|---|---| | loading | boolean | false | Show spinner and disable the button | | spinnerPosition | "left" \| "right" | "left" | Which side the spinner appears on | | spinnerGap | string \| number | "0.45em" | Gap between spinner and button label | | spinnerProps | Omit<BaseSpinnerProps, "size"> | — | Props forwarded to the inner <Spinner> |

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>

| Prop | Type | Default | Description | |---|---|---|---| | active | boolean | true | Show the overlay | | backdrop | string | "rgba(0,0,0,0.35)" | CSS background for the backdrop | | size | string \| number | "2rem" | Spinner glyph size | | containerStyle | CSSProperties | — | Style applied to the outer wrapper <div> | | containerClassName | string | — | Class applied to the outer wrapper <div> | | children | ReactNode | — | Content that gets overlaid |

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" />

| Prop | Type | Default | Description | |---|---|---|---| | defaultName | SpinnerName | "braille" | Default spinner name | | defaultColor | string | undefined | Default color | | defaultSize | string \| number | undefined | Default glyph size | | defaultSpeed | number | 1 | Default speed multiplier | | defaultShape | "circle" \| "square" \| "diamond" | undefined | Default dot shape | | respectReducedMotion | boolean | true | Pause animations when the OS has prefers-reduced-motion: reduce |

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