Documentation

Use OrbUX in your interface.

Register a custom element, set its state, and adjust it with attributes or CSS custom properties. Framework wrappers are not required.

Every OrbUX loader is a standard Web Component. It works in React, Vue, Svelte, Angular, or plain HTML with no wrapper, and shares one contract regardless of whether it's drawn with CSS, Canvas, or WebGL. Lottie is a future tier, not a current runtime dependency.

Quick start

Install from npm under the permanent @vikast908 scope (@vikast908/core and @vikast908/loaders). Product custom-element tags stay orbux-*. Use 0.1.1 or newer — loaders 0.1.0 shipped with a broken dependency and will not install cleanly.

npm install @vikast908/loaders@0.1.1 @vikast908/core@0.1.1

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

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

const orb = document.querySelector('orbux-pulse-orb');
orb.state = 'streaming';
orb.progress = 0.6; // determinate loaders only

No npm yet? Use Download HTML on any loader detail page for a self-contained demo, or clone this monorepo and run pnpm install && pnpm dev.

Standalone HTML

Every loader has a self-contained HTML demo with the browser bundle inlined. On a loader detail page, use Download HTML or Copy HTML. No build step is required — open the file in any modern browser. You can also open /orbux/<id>.html from the gallery (for example /orbux/pulse-orb.html).

The agent state model

The state attribute maps an agent lifecycle to visual behavior. The model is transport-agnostic and does not depend on an AI SDK.

State	Meaning
`idle`	Present but not working.
`thinking`	Reasoning; indeterminate.
`streaming`	Emitting output tokens.
`tool-calling`	Executing a tool or action.
`waiting`	Awaiting human input.
`done`	Completed successfully.
`error`	Failed.

Loaders declare which states they distinguish; unsupported states fall back gracefully. Use progress (0 to 1) for determinate loaders.

Theming

Theme with CSS custom properties. No rebuild is needed:

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

Accessibility & performance

Respects prefers-reduced-motion with a minimal or static presentation.
Sets role="status", aria-busy, and a state-derived label.
Determinate loaders switch to role="progressbar" with percentage values.
Auto-pauses CSS and rAF motion when scrolled offscreen or the browser tab is hidden (data-paused).
WebGL loaders clamp device-pixel-ratio and render a single static frame when paused.

If a theme changes on an ancestor, call loader.refreshTheme() or dispatch orbux:themechange on window. Import @vikast908/loaders/preflight.css to reserve loader dimensions before custom elements upgrade.

Framework notes

In React 19+, custom elements accept properties and attributes directly. In older React, pass state as an attribute (string). In Vue/Svelte/Angular, bind attributes as usual.

Back to the gallery