agent_orbs

Dotted thought-orb loading indicators for AI and agent UIs.
Nine tuned states, two sizes, automatic dark and light theming, rendered with a plain CustomPainter (no shaders).

An unofficial Flutter port of thinking-orbs by Jakub Antalik. The animation math and tunings are preserved verbatim; only the runtime (React canvas becomes a Flutter CustomPainter) differs. Live reference: orbs.jakubantalik.com.

Gallery

Install

Not yet published to pub.dev. Add it from Git (or a local path):

dependencies:
  agent_orbs:
    git:
      url: https://github.com/kwamerex101/agent_orbs.git

Once published, the usual applies:

dependencies:
  agent_orbs: ^0.1.0

Quick start

import 'package:agent_orbs/agent_orbs.dart';

// A 64px "searching" orb that follows the platform brightness.
const ThinkingOrb(state: OrbState.searching);

// Inline in a chat bubble, at the small design, pinned dark:
const ThinkingOrb(
  state: OrbState.working,
  size: 20,
  theme: OrbTheme.dark,
);

The nine states

Preview	State	Motion
	working	Particles run tilted orbits.
	searching	A scan meridian sweeps a dotted globe.
	solving	Bands scramble in quarter turns, then click back solved.
	listening	A waveform rolls through the latitude rings.
	connecting	A constellation wires itself, packets running the edges.
	weaving	Three strands plait around the sphere.
	composing	An undulating multi-band sash.
	breathing	A face-on ring slowly morphing.
	shaping	A dotted outline morphs circle, triangle, square.

API

ThinkingOrb properties:

Property	Type	Default	Notes
state	OrbState	working	Which of the nine animations to show.
size	double	64	Logical-pixel size. Tuning snaps to the nearer of the two designs (64 or 20); the orb draws at exactly this size.
theme	OrbTheme	auto	auto follows platform brightness; dark and light pin the palette.
speed	double	1	Multiplier on the preset's baked-in speed.
paused	bool	false	Freeze on the current frame.
semanticLabel	String?	per-state	Accessibility label override.

Theming

auto reads MediaQuery.platformBrightness. To follow an in-app theme toggle (for example a MaterialApp running in dark mode), pass the brightness explicitly:

ThinkingOrb(
  state: OrbState.connecting,
  theme: Theme.of(context).brightness == Brightness.dark
      ? OrbTheme.dark
      : OrbTheme.light,
);

Dark renders light ink on the transparent canvas (for dark backgrounds); light renders dark ink (for light backgrounds).

Sizes

Two designs ship, each separately tuned for dot count, dot size and speed: the 64px chat-avatar scale and the 20px inline-text scale. Any size you pass snaps to the nearer design for tuning, then draws at your exact size.

Reduced motion and performance

• Honors MediaQuery.disableAnimations: a single representative frame is drawn instead of animating.
• Each orb drives one Ticker, which the framework mutes while the widget is offscreen (TickerMode).
• A single shared clock keeps orbs of the same preset in phase.
• Plain z-sorted circle fills. No shaders, no image filters, identical across platforms.

Power-user API

Drive the raw frame painters yourself, for a custom canvas or a one-off render:

final resolved = resolvePreset(OrbState.weaving, OrbSize.large);
modeDraws[resolved.mode]!(canvas, 128, t, /* dark: */ true, resolved.opts);

resolvePreset, Resolved, ModeKey, modeDraws, Dot, Line and ModeOpts are all exported.

Example

A runnable gallery with size, speed, theme and pause controls lives in example/:

cd example
flutter run

Credits

All credit for the original concept, design, and animation engine goes to Jakub Antalik:

• Source: github.com/Jakubantalik/thinking-orbs (MIT)
• Live demo: orbs.jakubantalik.com

This package is an unofficial Flutter port. It preserves that engine's math and per-state tunings verbatim; only the rendering is reimplemented on Flutter's CustomPainter. If you like these orbs, please star the original project.

Flutter port by Rex Danquah.

License

MIT. See LICENSE.