Orb

A 3D animated orb with audio reactivity, custom colors, and agent state visualization built with Three.js.

Agent Orbs

Interactive orb visualization with agent states

Installation

npx shadcn-svelte@latest add https://sv11.ui.twango.dev/r/orb.json

Usage

<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";
</script>
 
<Orb />

Examples

Custom Colors

Pass a two-tuple of hex colors to replace the default gradient.

<Orb colors={["#FF6B6B", "#4ECDC4"]} />

Audio Reactivity

Sample live input and output volumes every frame by passing getInputVolume and getOutputVolume. Each should return a normalized value in [0, 1].

<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";
 
	function getInputVolume() {
		// Return normalized microphone volume between 0 and 1.
		return 0.5;
	}
 
	function getOutputVolume() {
		// Return normalized agent-output volume between 0 and 1.
		return 0.7;
	}
</script>
 
<Orb {getInputVolume} {getOutputVolume} />

Custom Seed

Pass a seed for a deterministic orb shape — useful when you want a specific look to persist across reloads.

<Orb seed={12345} />

Agent State

Drive the orb's visual behavior from an agent lifecycle value. Pass null to render the idle state.

<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";
	import type { OrbAgentState } from "$lib/registry/ui/orb";
 
	let agentState: OrbAgentState = $state(null);
</script>
 
<Orb {agentState} />

Manual Volume Control

Switch volumeMode to "manual" and drive reactivity from reactive state instead of live audio streams.

<script lang="ts">
	import { Orb } from "$lib/registry/ui/orb";
 
	let inputVolume = $state(0.5);
	let outputVolume = $state(0.7);
</script>
 
<Orb volumeMode="manual" manualInput={inputVolume} manualOutput={outputVolume} />

API Reference

Prop	Type	Default	Description
`colors?`	`[string, string]`	`["#CADCFC", "#A0B9D1"]`	Two hex colors sampled across the orb's gradient. Update reactively to animate between palettes.
`seed?`	`number`	—	Seed for the orb's internal noise, determining its overall shape. Defaults to a stable per-instance random value so multiple orbs on one page look distinct.
`agentState?`	`OrbAgentState`	`null`	Drives the orb's visual behavior to reflect the agent lifecycle. Pass `null` to render the idle state.
`volumeMode?`	`"auto" \| "manual"`	`"auto"`	`"auto"` uses the active microphone and output audio streams to drive reactivity. `"manual"` reads `manualInput` / `manualOutput` (or the `get*Volume` callbacks) instead.
`manualInput?`	`number`	—	Manual input volume in `[0, 1]`. Only read when `volumeMode="manual"`.
`manualOutput?`	`number`	—	Manual output volume in `[0, 1]`. Only read when `volumeMode="manual"`.
`getInputVolume?`	`() => number`	—	Called every frame to sample input volume in `[0, 1]`. Takes precedence over `manualInput` when both are provided.
`getOutputVolume?`	`() => number`	—	Called every frame to sample output volume in `[0, 1]`. Takes precedence over `manualOutput` when both are provided.

Notes

Built on Three.js and @threlte/core for performant WebGL rendering from Svelte.
Pass functions (getInputVolume / getOutputVolume) for live audio, or manualInput / manualOutput with volumeMode="manual" for direct control. The callbacks take precedence when both are set.
Reactive props (colors, agentState) update smoothly — you can animate palette transitions by mutating $state without remounting.
seed defaults to a stable per-instance random value, so multiple orbs on the same page render distinct shapes by default.
Canvas resizing is handled internally — the orb fills its container and re-renders on layout changes.

Mic Selector Response