OrbUX

Loaders for AI and agent interfaces.

OrbUX collects small CSS indicators, Canvas animations, and WebGL effects behind one Web Component API. Each loader responds to agent states such as thinking, streaming, tool-calling, waiting, done, error, and cancelled.

236 loaders · CSS/SVG · Canvas 2D · WebGL · no third-party runtime dependencies · MIT

---

Why

Generic loading indicators usually expose only active and inactive states. Agent interfaces also need to show thinking, streaming, tool calls, waiting, completion, and failure. OrbUX gives those states one component contract across three rendering tiers.

• Framework-agnostic. Standard Web Components work in React, Vue, Svelte, Angular, and plain HTML.
• State-driven. Set state="streaming" and the loader changes its motion and presentation.
• Copy-paste friendly. Import one package subpath, use a browser bundle, or download a standalone HTML demo.
• Three rendering tiers. CSS/SVG, Canvas 2D, and raw WebGL. Lottie is not implemented yet.

Quick start

Install from npm

Packages ship under the @vikast908 scope (product tags stay orbux-*):

Package	npm
@vikast908/core	npmjs.com/package/@vikast908/core
@vikast908/loaders	npmjs.com/package/@vikast908/loaders

npm install @vikast908/loaders@0.2.2 @vikast908/core@0.2.2

Use 0.2.2 or newer. (@vikast908/loaders@0.1.0 shipped with a broken dependency and is deprecated on npm, so avoid it.)

Register only the loader you need:

import '@vikast908/loaders/pulse-orb';
import '@vikast908/loaders/pulse-dots';

<orbux-pulse-orb state="thinking" size="140px"></orbux-pulse-orb>
<orbux-pulse-dots state="streaming"></orbux-pulse-dots>

Drive it from your agent code:

const orb = document.querySelector('orbux-pulse-orb');
orb.state = 'tool-calling';   // idle | thinking | streaming | tool-calling | waiting | done | error | cancelled
orb.progress = 0.6;           // optional 0..1 for determinate loaders
orb.pulse();                  // optional: call per streamed token to track real throughput

Listen for transitions, or map an SDK onto the state model with the optional, tree-shakeable @vikast908/core/adapters (Vercel AI SDK, AG-UI, OpenAI streaming, abort → cancelled):

orb.addEventListener('orbux:statechange', (e) => console.log(e.detail.previous, '→', e.detail.state));

import { fromVercelStatus } from '@vikast908/core/adapters';
orb.state = fromVercelStatus(status, { hasMessages: messages.length > 0 });

Theme it with CSS custom properties. No rebuild is needed:

orbux-pulse-orb {
  --orbux-size: 160px;
  --orbux-width: 160px;
  --orbux-height: 72px;
  --orbux-color: #6366f1;
  --orbux-color-2: #a855f7;
  --orbux-color-success: #22c55e;
  --orbux-color-error: #ef4444;
  --orbux-color-cancelled: #94a3b8; /* neutral stop cue */
  --orbux-color-progress: #38bdf8;
  --orbux-speed: 1; /* optional; same as the speed attribute */
}

Standalone HTML (no build)

Every loader also ships as a self-contained HTML demo with the minified bundle inlined. On a loader detail page use Download HTML or Copy HTML (✓ Copied / Copy failed), or build the demos:

pnpm browser-bundles
# → apps/site/public/orbux/<id>.html  (open in any browser)
# → apps/site/public/orbux/<id>.js    (ESM browser bundle)

With the site running: /orbux/pulse-orb.html or Download HTML on /loaders/pulse-orb. The detail page inspector adjusts state, size, speed, colors, and progress. Double-click progress to turn it off.

No build (CDN)

Load a single loader straight from a CDN as an ES module, with no bundler or install step:

<script type="module">
  import 'https://esm.sh/@vikast908/loaders@0.2.2/pulse-orb';
</script>
<orbux-pulse-orb state="thinking" size="140px"></orbux-pulse-orb>

The collection

Tier	Loaders
CSS/SVG (225)	25 handcrafted loaders, including 11 signature effects, plus 200 structural recipes built from 20 forms and 10 motion patterns
Canvas 2D (5)	Particle Swarm · Neural Nodes · Ripple Field · Flow Field · Waveform Scope
WebGL (6)	Pulse Orb · Aurora Orb · Liquid Metal · Plasma Field · Gradient Blob · Energy Core

The recipe catalog combines 20 structures with 10 motion patterns. State, size, speed, and color are component controls, not separate loaders. Each motion is rendered per layout: orbit revolves dots around a ring but sways bars in a traveling wave, fold squashes solid pieces on the X axis but folds concentric rings flat, so no two recipes animate identically, and every recipe stays inside its host box.

The signature loaders are written individually. They cover energy sigils, flame, smoke, water, ice, lightning, magic, cosmic, and cyber themes. Each has its own markup and motion.

packages/loaders/src/recipe-catalog.json is the canonical recipe manifest. Run pnpm catalog:generate after changing it; generated adapter folders are marked and reconciled automatically. Catalog sizes are measured from minified browser bundles and displayed gzip-compressed.

Every loader reacts to all eight states, is themeable through --orbux-*, and inherits reduced-motion, role="status", and offscreen pause behavior from the base classes. Loader runtime code has no third-party dependencies. The WebGL loaders use the browser API directly.

For layouts sensitive to upgrade timing, import @vikast908/loaders/preflight.css. When theme tokens change on an ancestor, call loader.refreshTheme() or dispatch orbux:themechange on window.

Repository layout

packages/core      # @vikast908/core: state model + base classes
                   #   OrbuxElement (contract, a11y, reduced-motion, pause),
                   #   Canvas2DElement (canvas + DPR + loop),
                   #   ShaderElement (full-screen fragment-shader boilerplate)
packages/loaders   # @vikast908/loaders: one folder per loader
registry/          # metadata schema and generated gallery registry
apps/site          # Astro gallery and documentation
scripts/           # registry, catalog, bundle, scaffolding, and browser/UI verification

Develop

pnpm install
pnpm dev             # build the registry and run the gallery at localhost:4321
pnpm registry        # regenerate registry/registry.json
pnpm typecheck       # type-check core, loaders, and the Astro site
pnpm browser-bundles # build /orbux/<id>.js + standalone /orbux/<id>.html demos
pnpm site:build      # build the registry and static gallery
pnpm test            # build packages and run contract/catalog tests
pnpm test:browser    # Chromium lab contract
pnpm test:ui         # Chromium gallery UI audit
pnpm new:loader <id> [css-svg|canvas|webgl|lottie]   # scaffold a new loader
pnpm publish         # publish @vikast908/core then @vikast908/loaders (requires npm auth)

Adding a loader: pnpm new:loader my-loader canvas, implement it, register it in packages/loaders/src/index.ts, then run pnpm registry. The gallery reads it automatically.

Packages

Package	Description
@vikast908/core	Agent state model, base elements, motion, theming
@vikast908/loaders	Full loader catalog and per-loader subpath exports

Publish is automated on v* tags via .github/workflows/npm-publish.yml when NPM_TOKEN is configured. Locally: pnpm publish after npm login.

See ROADMAP.md for planned work and CHANGELOG.md for shipped changes.

Community

• Read CONTRIBUTING.md before proposing a loader or submitting code.
• Use the issue chooser for bugs, documentation, features, and loader proposals; pull requests receive the review template automatically.
• Follow the Code of Conduct in every project space.
• Use SUPPORT.md to choose the right help or issue channel.
• Follow SECURITY.md before disclosing a vulnerability; public reports are prohibited.
• Project roles and decisions are described in GOVERNANCE.md.
• User-facing changes are tracked in CHANGELOG.md.

License

MIT © OrbUX contributors