Token Bucket Rate Limiter Visualizer — Free JS Snippet

Rate limiting is usually described in one sentence ("limit users to N requests per second") that hides the actual design decision every API gateway has to make: what happens to a client that sends 10 requests in the first 100 milliseconds of a fresh minute, then goes quiet? A naive fixed-window counter either blocks that burst outright or, worse, lets it double up at a window boundary. The token bucket algorithm — used by AWS API Gateway, Stripe's API, and most CDN edge limiters — handles it differently, and this snippet implements the real mechanics rather than a stylized approximation of them.

The refill loop: continuous time, not discrete ticks

The bucket does not refill in visible per-second jumps. tick(now) runs on requestAnimationFrame and computes elapsed = (now - lastTick) / 1000 on every single frame, then adds elapsed * REFILL_RATE to the tokens float, capped at CAPACITY with Math.min. Because this happens roughly 60 times a second, refilling is visually continuous — the bucket-fill bar's height and the fractional pip both creep upward smoothly rather than snapping in whole-token jumps. This matters for accuracy: real token bucket implementations (including the ones behind AWS and Stripe's limiters) also track tokens as a continuous value internally and only ever check "is there at least 1.0 available" at request time, not at refill time.

Capacity and the two discrete visualizations of the same number

tokens is a single float between 0 and CAPACITY (10 in this demo). It is rendered two ways simultaneously: a liquid bucket-fill div whose height is set to tokens / CAPACITY * 100% for a smooth analog read, and a row of 10 .pip elements where pips below Math.floor(tokens) are fully lit, the pip at exactly Math.floor(tokens) shows the fractional remainder as a partial CSS gradient fill via a --fill custom property, and pips above that are empty. Both views are driven from the exact same tokens variable on every animation frame, so they never disagree with each other or with the numeric token-count readout.

Consuming a token: the actual rate-limit check

sendRequest() is the entire rate-limit decision, and it is two lines: if (tokens >= 1) { tokens -= 1; ...allow... } else { ...reject... }. There is no separate request-counting window, no timestamp bucket, no sliding array of recent request times — the single tokens float is simultaneously the rate limiter's entire state. A green flash on the bucket panel and a log entry confirm an allowed request; a red flash and a distinct log entry confirm a rejection, with both counted in the Allowed/Rejected stat tiles so the outcome is never just a color you have to trust.

Why burst tolerance is the actual point, demonstrated with real math

The Burst Click button fires 6 sendRequest() calls 110ms apart — well within the same second, so almost no natural refill happens between them. Starting from a full bucket of 10 tokens, all 6 succeed instantly, because the bucket had capacity sitting banked from before the burst even started. This is the core behavior a fixed-window counter cannot replicate cleanly: a client that has been idle is allowed to spend its saved-up capacity all at once, up to CAPACITY, without being throttled mid-burst. Click Burst Click again immediately afterward with only 4 tokens left banked (10 minus the 6 just spent, still recovering at 1/sec) and watch some of the second burst get rejected — the system is not "10 requests per second" in the way a naive counter would enforce it, it is "spend up to 10 banked tokens instantly, then settle into a steady 1-per-second replenishment rate," which is exactly the guarantee real APIs advertise as their both burst allowance and sustained rate limit in the same sentence.

Why not a fixed-window counter instead

A fixed-window limiter resets a request counter to zero every fixed interval (e.g. every 1000ms) and rejects once the counter hits the limit within that window. Its failure mode is the classic "boundary burst": a client can send the full limit at the very end of one window and the full limit again at the very start of the next, delivering 2x the intended rate in a short span straddling the boundary, something the continuously-draining, continuously-refilling token bucket in this snippet structurally cannot do, because there is no window edge for two bursts to stack across.