Skip to main content
Clever Ops

Swarm Count

Particle swarm preloader for React, thousands of ink specks continually re-form the live percent numeral as progress advances. Seeded, deterministic canvas themed by Tailwind tokens.

Preview & code

Loading Swarm Count preview

Installation

pnpm dlx shadcn@latest add @cleverui/loader-swarm-count

Requires the @cleverui registry in your components.json, a one-off, two-line setup.

Usage

tsx
import { LoaderSwarmCount } from '@/components/ui/loader-swarm-count'
Exampletsx
'use client'

import { useEffect, useState } from 'react'
import { useReducedMotion } from 'motion/react'
import { LoaderSwarmCount } from '@/components/ui/loader-swarm-count'

export default function LoaderSwarmCountDemo() {
  const reduced = useReducedMotion()
  const [progress, setProgress] = useState(0)

  useEffect(() => {
    if (reduced) {
      setProgress(47)
      return
    }
    const start = performance.now()
    let raf = 0
    const tick = (now: number) => {
      const t = Math.min(1, (now - start) / 10000)
      // stepped-feeling ease so integer retargets are visible
      const eased = 1 - Math.pow(1 - t, 1.8)
      setProgress(eased * 100)
      if (t < 1) raf = requestAnimationFrame(tick)
    }
    raf = requestAnimationFrame(tick)
    return () => cancelAnimationFrame(raf)
  }, [reduced])

  return (
    <div className="mx-auto w-full max-w-5xl px-4 py-10 sm:px-6">
      <div className="overflow-hidden rounded-2xl border border-border/60">
        <LoaderSwarmCount
          progress={progress}
          caption="LOADING"
          label="Assembling readout"
          particles={1600}
        />
      </div>
    </div>
  )
}

The example itself also uses motion , install it too if you copy the example as-is (the component itself does not need it).

API reference

LoaderSwarmCount accepts the following props.

PropTypeDefaultDescription
progress*numberdeterminate 0-100; the swarm re-targets to the new numeral on every integer change
particlesnumber1800swarm budget on desktop, halved on coarse pointers
captionstring'LOADING'mono micro-label under the digits; the live percent is appended as real text
labelstring'Loading'seeds the aria announcement text

…plus everything from React.HTMLAttributes<HTMLDivElement>: className, event handlers, aria attributes and the rest pass straight through.

Frequently asked questions

How do I install the Swarm Count component?

Register the @cleverui registry in your components.json ("@cleverui": "https://cleverops.com.au/r/{name}.json"), then run `npx shadcn@latest add @cleverui/loader-swarm-count`. The shadcn CLI copies the source into your project, you own the code from that point. You can also copy the source directly from this page.

What dependencies does Swarm Count require?

Swarm Count has no npm dependencies beyond React and Tailwind CSS itself, so there is nothing extra to install or keep updated.

Can I theme Swarm Count to match my brand?

Yes. The component is styled entirely with Tailwind utilities over standard design tokens (primary, background, muted, border), so it inherits your existing shadcn/ui theme automatically. Change your CSS variables and the component follows, no source edits needed for palette, radius, or fonts.

Want this built for you?

CleverUI is built by the Clever Ops web team. If you'd rather ship a hand-coded, fast, custom website than assemble one, we build them for Australian businesses every week.

Explore web development services