How It Works — 3 Pixel Grid

The grid

The pixel grid is a 3×3 matrix of cells. Each cell has an index from 0 to 8, read left-to-right, top-to-bottom:

0 1 2 3 4 5 6 7 8

The delays array maps directly to these positions. delays[0] controls the top-left cell, delays[4] controls the center, delays[8] controls the bottom-right.

Delays

Each value in the delays array is a time in milliseconds. It controls when that cell turns on (and later off) during each animation cycle. Lower values fire first.

Take wave-lr. Its delays sweep left to right:

0 120 240 0 120 240 0 120 240

The left column (cells 0, 3, 6) has a delay of 0 — they fire immediately. The middle column fires at 120ms, and the right at 240ms. The result: a wave that rolls from left to right.

delays: [0, 120, 240, 0, 120, 240, 0, 120, 240]

Reading patterns

Once you see delays as a 3×3 map, patterns become intuitive. Here's center-out — the center cell fires first, its neighbours next, then the corners last:

240 120 240 120 0 120 240 120 240

And diagonal-tl — delays increase diagonally from the top-left corner:

0 100 200 100 200 300 200 300 400

delays: [0, 100, 200, 100, 200, 300, 200, 300, 400]

Duration

The duration value (in milliseconds) controls how long the engine holds before reversing. After all cells have turned on, the engine waits for the longest delay plus the duration, then runs the same staggered sequence to turn them off.

Short durations (100–160ms) create snappy, rhythmic pulses. Longer durations (200–260ms) give a more flowing, breathing feel. The sweet spot for most patterns is 150–220ms.

Color

The color field sets the color for all 9 cells. Pass a named color string and every cell in the grid lights up in that color.

Here's spiral-cw in orange:

color: 'orange'

12 named colors are available: cyan, magenta, yellow, green, orange, blue, red, purple, white, teal, pink, lime.

You can also pass a hex value instead of a name — for example #ff6600 or #e0f. The engine derives the dim and glow states automatically.

Multi-color

Instead of a single color, you can assign a different color to each cell using the colors array — 9 values, one per cell, in the same index order as delays. Each value can be a named color or a hex.

Here's frost — blue on the corners, cyan on the edges, white at the center:

blue cyan blue cyan white cyan blue cyan blue

colors: ['blue', 'cyan', 'blue', 'cyan', 'white', 'cyan', 'blue', 'cyan', 'blue']

Putting it all together

A single-color config:

PixelGrid.create(element, {
  animation: {
    name: 'spiral-cw',
    delays: [0, 80, 160, 560, 640, 240, 480, 400, 320],
    duration: 180,
    color: 'orange'
  }
})

A multi-color config:

PixelGrid.create(element, {
  animation: {
    name: 'frost',
    delays: [240, 120, 240, 120, 0, 120, 240, 120, 240],
    duration: 200,
    colors: ['blue', 'cyan', 'blue', 'cyan', 'white', 'cyan', 'blue', 'cyan', 'blue']
  }
})

The name is a label. The delays define the pattern. The duration sets the pace. Use color for a uniform color, or colors to assign one per cell. Both accept named colors or hex values. That's the entire API.