Sphere

GPU-accelerated particle sphere visualization with 256K particles, 6 geometry modes, 5 color schemes, and think-mode animation effects.

Sphere uses "use client" and dynamically imports Three.js inside useEffect. It renders an empty <div> during SSR and hydrates the WebGL canvas on the client. No additional configuration is needed for Next.js.

Geometry Modes

Six particle distribution algorithms, each with unique shader displacement:

Mode	Description
`sphere`	Fibonacci sphere with dual-layer noise displacement and tangential swirl
`curl`	Curl noise flow field along the sphere surface
`turing`	Reaction-diffusion pattern (activator-inhibitor model)
`lorenz`	Lorenz strange attractor trajectory sampling
`tendrils`	80 radial tendrils emanating from the sphere surface

<Sphere mode="lorenz" colorScheme="ember" />

Color Schemes

Five built-in gradient schemes (5 stops each, bottom to top):

Scheme	Description
`solar`	Warm gold to cool blue-white (default)
`aqua`	Deep teal to bright cyan
`ember`	Deep red-brown to warm off-white
`aurora`	Green to purple northern lights
`ghost`	Monochrome grayscale

Custom Colors

Override with a 5-stop gradient array (RGB values in 0-1 range):

<Sphere
  colors={[
    [0.1, 0.0, 0.3],
    [0.3, 0.0, 0.6],
    [0.5, 0.1, 0.8],
    [0.7, 0.3, 0.9],
    [0.9, 0.6, 1.0],
  ]}
/>

Think Mode

The sphere supports a "thinking" animation with three layered effects:

Pulses — Expanding ring waves from random surface points
Ramp — Speed boost during think intensity
Scatter — Staccato heartbeat contractions that scatter particles outward

Declarative Control

<Sphere thinkIntensity={0.8} thinkEffects={{ pulses: true, ramp: true, scatter: true }} />

Imperative Control

Use a ref for start/stop with automatic ease ramping:

const sphereRef = useRef<SphereRef>(null);

<Sphere ref={sphereRef} />

// Start thinking (automatic ease-in)
sphereRef.current?.startThinking();

// Stop thinking (automatic ease-out)
sphereRef.current?.stopThinking();

Visual Tuning

Fine-tune the visualization appearance:

<Sphere
  speed={1.5}       // Animation speed multiplier
  waves={2}         // Noise displacement intensity
  dotSize={0.8}     // Particle size
  blur={0.6}        // Softness (0 = hard dots, 1 = full glow)
  saturation={1.2}  // Color saturation
  lightness={0.9}   // Color lightness
  scale={1.0}       // Overall scale
/>

Orbit Controls

Drag to rotate, scroll to zoom. Disable with orbitControls={false}.

<Sphere orbitControls autoRotate autoRotateSpeed={0.5} />

Reduced Motion

When prefers-reduced-motion: reduce is active, the animation freezes in place and auto-rotation stops. The sphere remains visible as a static image. Orbit controls still respond to user interaction.

Ref API

Method	Description
`startThinking()`	Start think mode with automatic ease-in ramp
`stopThinking()`	Stop think mode with automatic ease-out ramp
`getThinkIntensity()`	Get current think intensity (0-1)
`setThinkIntensity(value)`	Set think intensity directly (0-1)
`setMode(mode)`	Switch geometry mode
`setColorScheme(scheme)`	Apply a named color scheme
`setColors(colors)`	Apply custom gradient colors
`resetCamera()`	Animated camera reset to default position
`dispose()`	Force dispose of all GPU resources

Performance

256K particles rendered in a single GPU draw call (THREE.Points)
All visual computation runs in GLSL shaders — CPU updates ~10 uniforms per frame
Additive blending creates natural bright hotspots without extra computation
Device pixel ratio clamped to 2 by default (maxPixelRatio prop)
Targets 60fps on modern hardware

Installation

npx visor add sphere

This installs three (~150KB gzipped) as a dependency. If your project already uses Three.js, the existing installation will be reused.

Usage

import { Sphere } from '@/components/visual/sphere/sphere';

<div style={{ width: '100%', height: '400px' }}>
  <Sphere colorScheme="solar" mode="sphere" />
</div>

The Sphere component fills its container. Wrap it in a sized element.

API Reference

SphereProps

Prop	Type	Default	Description
`mode`	`'sphere' \| 'curl' \| 'turing' \| 'lorenz' \| 'tendrils'`	`'sphere'`	Geometry mode for particle distribution.
`colorScheme`	`'solar' \| 'aqua' \| 'ember' \| 'aurora' \| 'ghost'`	`'solar'`	Named color scheme. Overridden by colors if both are provided.
`colors`	`GradientColors`	—	Custom 5-stop gradient colors (RGB 0-1 range). Overrides colorScheme.
`particleCount`	`number`	`256000`	Number of particles rendered.
`radius`	`number`	`1.2`	Sphere radius.
`scale`	`number`	`1.0`	Overall scale multiplier.
`speed`	`number`	`1.0`	Animation speed multiplier.
`waves`	`number`	`1.0`	Noise displacement multiplier (wave amplitude).
`dotSize`	`number`	`1.0`	Particle size multiplier.
`blur`	`number`	`0.5`	Particle softness (0 = hard dots, 1 = full glow).
`saturation`	`number`	`1.0`	Color saturation multiplier.
`lightness`	`number`	`1.0`	Color lightness multiplier.
`thinkIntensity`	`number`	`0`	Think-mode intensity (0–1). Controls layered animation effects.
`thinkEffects`	`SphereThinkEffects`	—	Which think-mode effects are enabled (pulses, ramp, scatter). All enabled by default.
`orbitControls`	`boolean`	`true`	Enable drag-to-rotate orbit controls.
`autoRotate`	`boolean`	`true`	Enable automatic rotation.
`autoRotateSpeed`	`number`	`0.5`	Auto-rotation speed.
`maxPixelRatio`	`number`	`2`	Max device pixel ratio (clamped for performance).
`backgroundColor`	`number`	`0x000000`	Background color as a hex number.
`className`	`string`	—	Additional CSS class for the container div.
`style`	`React.CSSProperties`	—	Inline style for the container div.

Accessibility

The sphere is a purely decorative visualization — it conveys no information that must be accessible.
Wrap in aria-hidden="true" when used as pure decoration so screen readers skip it entirely.
prefers-reduced-motion is respected: animation and auto-rotation stop automatically when the OS setting is active.
Do not use Sphere as a primary means of conveying status or data — pair it with text or other accessible indicators.

{/* Decorative usage */}
<div aria-hidden="true">
  <Sphere colorScheme="solar" />
</div>