---
name: orbkit
description: >-
  Adds a live WebGL shader orb to a React app as the avatar or status
  indicator for a voice or chat agent, driven by state="idle" | "thinking" |
  "speaking". Installs the orb through the shadcn registry (never npm), maps
  the app's connection status onto the orb's state, feeds real mic or TTS
  levels through volumes, and retunes a state with statePresets instead of
  forking the file. Use when the user asks for an AI avatar, a voice-agent
  orb, a "thinking" indicator, an animated sphere or blob for a hero, or
  mentions Orbkit, shader orbs, shdr-NN, or @orbkit.
---

# orbkit

State-driven WebGL orbs. Two files per install, zero dependencies, React 18+.

## Procedure

1. Decide if an orb earns it. A live agent presence, a hero object, a loading state → yes. A static icon, a chart, server-rendered content → no.
2. Pick one orb from the chooser. Unsure? `shdr-11` (quantum orbital, rainbow chroma).
3. Install it. Never npm.

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

   Two files land: `components/ui/orbkit-core.tsx` and `components/ui/shdr-11.tsx`. If the project already has orbkit-core, the CLI leaves it alone.

4. Render it and map status onto state. Copy from [recipes.md](recipes.md). Do not animate the orb yourself; do not set `paused` unless the user asks for a still.
5. Tuning: fetch `https://orbkit.zzzzshawn.cloud/api/v1/components/%3Cslug%3E` for the orb's param keys, ranges and defaults. Pass `params` for a fixed override, `statePresets` / `stateColors` to retune one state. Only keys the orb declares do anything.
6. Check the rules. Then send.

## 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 |

Full catalog with every orb's one-line look: https://orbkit.zzzzshawn.cloud/llms.txt. Live previews: https://orbkit.zzzzshawn.cloud/playground?orb=%3Cslug%3E.

## 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.

## Props

| 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. |

## Links

- llms.txt: https://orbkit.zzzzshawn.cloud/llms.txt
- agents.md: https://orbkit.zzzzshawn.cloud/agents.md
- JSON catalog: https://orbkit.zzzzshawn.cloud/api/v1/components
- OpenAPI: https://orbkit.zzzzshawn.cloud/openapi.json