I Built an Animated Marble Diagram for Spring WebFlux / Project Reactor

Reactive code reads like a list of operators but behaves like a stream over time — which is exactly what a plain code sample can't show you. Marble diagrams are the classic way to explain Reactor/RxJS, so I built an animated, interactive one for the Spring WebFlux Flux/Mono API.

▶ Live demo: https://dev48v.github.io/webflux-marbles/
Source (single file, zero deps): https://github.com/dev48v/webflux-marbles

Toggle operators, press play, and a playhead sweeps the timeline revealing each source and output marble.

What you're watching

Flux.range(1, 8)
    .filter(n -> n % 2 == 0)   // drop odds → 2,4,6,8
    .map(n -> n * 2)           // double     → 4,8,12,16
    .take(3)                   // first 3, then COMPLETE → 4,8,12 |
    .subscribe(System.out::println);   // nothing runs until here

Source lane: 1..8. Output lane: 4, 8, 12, then a green onComplete bar. Turn filter off and more marbles flow; add delayElements and the whole output lane shifts right; flip to Mono and the source emits at most one value.

Three things it makes obvious

Operators are lazy. Building the chain does nothing — it just describes a pipeline. Work starts only when you subscribe(). That's why the demo does nothing until you press play, and why a @GetMapping returning a Flux doesn't execute until the framework subscribes.

take short-circuits upstream. Once take(3) has its three, it cancels the source. Over an expensive or infinite source (Flux.interval(...)), the upstream simply stops — later values never run. You can watch the stream complete early on the green bar while source marbles 7 and 8 are still visible but never produced output.

Everything is a stream over time, not a collection. The values arrive spread across the timeline; order and timing (delayElements) are first-class. That's the whole mental shift from imperative for loops to reactive pipelines — and the reason WebFlux can handle many concurrent requests on few threads.

Why a marble diagram beats prose

You can read "take completes the stream" and still be fuzzy on whether the source keeps running. Seeing the green bar drop and the later source marbles produce nothing settles it in a second.

If this made reactive streams click, a star helps others find it: https://github.com/dev48v/webflux-marbles