# Orbkit

Orbkit is a React component library of WebGL shader orbs — expressive, state-driven orbs you install via the shadcn registry and own as local code.
https://orbkit.zzzzshawn.cloud

Orbs are state-driven avatars for voice and chat agents: pass state="idle" | "thinking" | "speaking" and the orb's motion, colour and energy follow. Source is copied into your project via the shadcn registry, not npm. Zero runtime dependencies. WebGL 1.

## When to use

Use Orbkit when an agent is building a UI that needs a live, expressive presence: a voice-assistant avatar, a status indicator for an LLM call, a hero object on a landing page, a loading state that should feel alive.

Do not use it for a static icon, a chart, or anything that has to render on the server or without WebGL.

## How to call it

1. Install one orb (the shared runtime comes along automatically):

   npx shadcn@latest add https://orbkit.zzzzshawn.cloud/r/shdr-11.json

   Or, if the project's components.json aliases the @orbkit registry: npx shadcn@latest add @orbkit/shdr-11

2. Render it and map your agent's status onto its state:

```tsx
import { Shdr11 } from "@/components/ui/shdr-11";

const orbState =
  status === "connecting" ? "thinking"
  : isAgentSpeaking ? "speaking"
  : "idle";

<Shdr11 size={320} state={orbState} />
```

3. Install the skill from https://orbkit.zzzzshawn.cloud/skill.md so the chooser and the rules run without fetching this file every time.

## Machine-readable

- For agents (HTML): https://orbkit.zzzzshawn.cloud/agents
- agents.md: https://orbkit.zzzzshawn.cloud/agents.md
- llms.txt: https://orbkit.zzzzshawn.cloud/llms.txt
- Skill: https://orbkit.zzzzshawn.cloud/skill.md
- Recipes: https://orbkit.zzzzshawn.cloud/skill/recipes.md
- Developer API: https://orbkit.zzzzshawn.cloud/developers
- OpenAPI: https://orbkit.zzzzshawn.cloud/openapi.json
- API index: https://orbkit.zzzzshawn.cloud/api/v1
- Health: https://orbkit.zzzzshawn.cloud/api/v1/health
- JSON catalog: https://orbkit.zzzzshawn.cloud/api/v1/components
- One orb (full param schema and presets): https://orbkit.zzzzshawn.cloud/api/v1/components/%3Cslug%3E
- Registry item (the source shadcn installs): https://orbkit.zzzzshawn.cloud/r/%3Cslug%3E.json
- Registry index: https://orbkit.zzzzshawn.cloud/r/registry.json
- Sitemap: https://orbkit.zzzzshawn.cloud/sitemap.xml

## CLI

One orb:

npx shadcn@latest add https://orbkit.zzzzshawn.cloud/r/%3Cslug%3E.json

Every orb:

npx shadcn@latest add https://orbkit.zzzzshawn.cloud/r/all.json

Files land in components/ui/. The orb imports the runtime from @/components/ui/orbkit-core.

## States

- idle — calm, slow drift — the agent is listening or waiting
- thinking — restless motion with a slow wander — the agent is working
- speaking — fast, bright, strongly precessing — the agent is talking

Each state synthesizes two volume signals — input (user speech energy) and output (agent speech energy) — which the shader reads as uniforms. Params glide between states, and rate params are integrated into a clock, so a state change never jumps the animation.

## Props (every orb)

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| size | number | 280 | Rendered diameter in CSS pixels. |
| state | "idle" \| "thinking" \| "speaking" | "idle" | Drives the synthesized volume signals and selects the state preset. Params glide between states; the animation phase never jumps. |
| params | Partial<Record<string, number>> | — | Explicit shader-parameter overrides. Any key here wins over the state preset. Only keys the orb declares (see its params) do anything. |
| colors | Partial<Record<string, string>> | — | Hex colour overrides, for the colour keys the orb declares. |
| statePresets | Partial<Record<OrbState, Record<string, number>>> | — | Per-state param targets merged KEY BY KEY over the orb's own presets, so { thinking: { speed: 2 } } retunes one param of one state and leaves everything else as shipped. |
| stateColors | Partial<Record<OrbState, Record<string, string>>> | — | The colour counterpart of statePresets, merged the same way. |
| stateVolumes | Partial<Record<OrbState, { input?: number; output?: number }>> | — | Per-state volume drive (0..1 each), to give a state more or less energy. |
| volumes | { input?: number; output?: number } | — | Pins the live volume signals (0..1). input is user speech energy, output is agent speech energy. Feed a real mic or TTS level here; omit a channel to keep its synthesized motion. |
| paused | boolean | false | Freeze on the current frame. |
| pauseOffscreen | boolean | true | Stop rendering while scrolled out of view. |
| maxDpr | number | 2 | Device-pixel-ratio ceiling. |
| wrapper | OrbWrapper | "none" | Decoration drawn around the orb: none, glass, ring, dotted, ticks, reticle, grid, halftone, scanlines. Never changes the footprint. |
| wrapperColor | string | "currentColor" | What the wrapper draws its lines in. glass ignores it. |
| className | string | — | Applied to the outermost element. |
| style | CSSProperties | — | Merged onto the outermost element's style. |
| ariaLabel | string | — | When set the orb is role=img with this label; otherwise it is aria-hidden. |

## Rules

- One orb per agent, driven by `state`. Map your connection status onto idle / thinking / speaking; do not animate the orb yourself.
- Override only params the orb declares. Fetch /api/v1/components/<slug> for the exact keys, ranges and defaults; do not invent keys.
- Retune a state with `statePresets` / `stateColors` (merged key by key), not by forking the orb file.
- Feed a real signal through `volumes` (input = user speech energy, output = agent speech energy, both 0..1) when you have one; otherwise leave it synthesized.
- Keep mounted orbs under about a dozen per page — each is a WebGL context and browsers cap those near 16. `pauseOffscreen` (default true) handles scrolling, not count.
- Install through the shadcn CLI, never npm. Two files land: components/ui/orbkit-core.tsx (the runtime) and components/ui/<slug>.tsx (the orb). They import nothing but React.
- The runtime is a client component; the orb renders nothing on the server and needs no dynamic import. It respects prefers-reduced-motion by drawing one static frame.
- Use the `wrapper` prop for a bezel (glass, ring, dotted, ticks, reticle, grid, halftone, scanlines). Never wrap the canvas in your own border that changes its footprint.

## Chooser

| The ask | Try first | 
| --- | --- |
| A voice-assistant avatar with a clear state read | shdr-11, shdr-26, shdr-13 |
| Calm glass for a product hero or a loading state | shdr-01, shdr-25, shdr-21 |
| Retro, terminal, pixel, CRT, print | shdr-23, shdr-14, shdr-28, shdr-29, shdr-33, shdr-27 |
| Nature: water, weather, cloud | shdr-16, shdr-20, shdr-21, shdr-17 |
| Cosmic: galaxy, crystal, corona | shdr-32, shdr-18, shdr-31, shdr-22 |
| Ornament and pattern | shdr-02, shdr-19, shdr-30 |

Every orb, with its one-line look. Params and colours are the keys you may pass; fetch https://orbkit.zzzzshawn.cloud/api/v1/components/%3Cslug%3E for ranges and defaults.

| Slug | Component | Look | Params | Colours |
| --- | --- | --- | --- | --- |
| shdr-01 | Shdr01 | cut-glass orb with a dispersive, turbulent interior | 20 | tint |
| shdr-02 | Shdr02 | ornate scrollwork on a rolling dome | 15 | — |
| shdr-03 | Shdr03 | a turbulent belt of light girdling the ball, contoured in rainbow | 25 | tint |
| shdr-04 | Shdr04 | a hollow shell of light, faceted by a voxel lattice | 17 | tint |
| shdr-05 | Shdr05 | rainbow rings travelling through a lattice of lenses | 16 | tint, body, sheen |
| shdr-06 | Shdr06 | a hundred glowing lattices stacked through the ball, interfering | 14 | tint, sheen |
| shdr-07 | Shdr07 | a twist wave travelling out through the ball around a lit column | 23 | tint |
| shdr-08 | Shdr08 | mother-of-pearl contour bands, each layer its own hue | 18 | deep, low, crest, sheen |
| shdr-09 | Shdr09 | torn rings of rainbow light worn as the ball's latitudes | 18 | tint, sheen |
| shdr-10 | Shdr10 | a lattice of light knitted into the ball's own skin | 24 | tint |
| shdr-11 | Shdr11 | quantum orbital, rainbow chroma | 18 | — |
| shdr-12 | Shdr12 | a ball of glossy toy bricks, studs up — it rebuilds itself while it thinks | 13 | brickA, brickB, brickC, brickD, brickE |
| shdr-13 | Shdr13 | plasma globe: crawling lightning filaments | 23 | inner, arc, tint |
| shdr-14 | Shdr14 | a lit plasma dome quantized to chunky two-tone pixels | 11 | ink, paper |
| shdr-15 | Shdr15 | an iridescent particle-track web worn as the ball's skin | 19 | tint |
| shdr-16 | Shdr16 | sunlight through water — a caustic net crawling over the ball, fringing into colour where it moves | 13 | deep, sun, sheen |
| shdr-17 | Shdr17 | a grainy many-coloured storm with band shear and lightning | 18 | deep, low, mid, hot, flash |
| shdr-18 | Shdr18 | a crystal folded out of one eighth of space, tumbling | 20 | tint |
| shdr-19 | Shdr19 | beads swelling and shrinking in their cells, packed over the ball | 18 | low, high, body, sheen |
| shdr-20 | Shdr20 | a water film rushing down the ball, fountain-style | 21 | tint |
| shdr-21 | Shdr21 | light diffusing through a cloud | 18 | light, shadow |
| shdr-22 | Shdr22 | field lines swirling around the ball about a wandering axis | 22 | tint |
| shdr-23 | Shdr23 | an ASCII glyph matrix in CRT green, wrapped on the ball | 14 | glow, deep |
| shdr-24 | Shdr24 | a Minecraft Earth — a perfect voxel sphere whose seasons cycle it through lush, cherry-grove, ice, mesa and desert worlds | 19 | grass, dirt, stone, sand, water, leaf, ore, lava |
| shdr-25 | Shdr25 | the folds of a warped field, drawn by their own steepness | 18 | tint, body, sheen |
| shdr-26 | Shdr26 | a crazed web of coloured threads knotted to a cell grid | 18 | deep, line, hot, sheen |
| shdr-27 | Shdr27 | a weather-radar mosaic, fronts of coloured pixels sweeping the ball | 20 | paper, c0, c1, c2, c3, c4, c5, c6 |
| shdr-28 | Shdr28 | nested binary grids shuttering on a tumbling bit-sphere | 15 | lineA, lineB, base, rim |
| shdr-29 | Shdr29 | an LED tile wall lighting up in flowing blobs, wrapped on the ball | 14 | lit, wall |
| shdr-30 | Shdr30 | a meadow folding into itself toward a blue vanishing point | 24 | sky, cloud, canopy, meadow, water, bloom, sheen |
| shdr-31 | Shdr31 | raymarched shell, volumetric godrays | 20 | — |
| shdr-32 | Shdr32 | a galaxy marched as gas and dust inside the ball | 34 | tint, core, inner, outer, deep, rim |
| shdr-33 | Shdr33 | a thermal image, risograph-printed on the ball | 24 | cold, cool, warm, hot, core, paper |

## Playground

Every orb has a live playground with all three states and every param as a slider: https://orbkit.zzzzshawn.cloud/playground?orb=%3Cslug%3E&state=%3Cidle|thinking|speaking%3E. The playground emits the exact JSX for whatever you dial in.

## Credits

Built by zzzzshawn (https://x.com/zzzzshawn/). Source: https://github.com/zzzzshawn/orbkit. MIT.