Source: https://mokxi.com/libraries/adafruit-neomatrix
Updated: 2026-11-11

Libraries / LEDs

Arduino library · LEDs

# Adafruit NeoMatrix: text and shapes on a WS2812 LED grid

A WS2812 panel is a single strip of LEDs folded into a grid, so the LED at (x, y) has a number that depends on how the strip was laid out. Adafruit_NeoMatrix does that sum for you and puts the Adafruit_GFX drawing calls on top: print(), drawLine(), drawRect(), fillCircle() and bitmaps all take x and y, and the library finds the right LED.

Open the example in the editor See the calls

Built in on Mokxi: #include <Adafruit_NeoMatrix.h> and it builds, with nothing to install. Free, and no account needed.

## What Adafruit NeoMatrix does

The matrix type flags describe the wiring. NEO_MATRIX_TOP or BOTTOM and LEFT or RIGHT name the corner where LED 0 is; ROWS or COLUMNS say which way the strip runs; PROGRESSIVE means every line starts at the same side, ZIGZAG that each line turns back. Most flexible 8x8 and 16x16 panels are zigzag, and getting this wrong is the reason for most scrambled pictures. Tiled panels add NEO_TILE_ flags for how the tiles are chained.

Colors are 16-bit, as Adafruit_GFX uses, made with matrix.Color(r, g, b). The class is an Adafruit_NeoPixel underneath, so it runs on the same boards and needs the same three includes: Adafruit_GFX.h, Adafruit_NeoMatrix.h and Adafruit_NeoPixel.h. The runnable example draws a box on an 8x8 zigzag panel and prints its size.

Library Manager name | Adafruit NeoMatrix

Author | Adafruit

Include | #include <Adafruit_NeoMatrix.h>

Boards | Arduino Uno, Arduino Nano, Arduino Mega 2560, Arduino Leonardo, SparkFun Pro Micro, Arduino Micro, Arduino Pro Mini 3.3 V, ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, Raspberry Pi Pico, Raspberry Pi Pico W, Arduino Nano RP2040 Connect, Seeed XIAO RP2040, Waveshare RP2040-Zero, Arduino Uno R4, Arduino Uno R4 WiFi

In the simulator | Simulated: it runs against the part the way it does on the bench.

Parts it drives | Addressable RGB LEDs

## Install it

It builds on Arduino Uno, Arduino Nano, Arduino Mega 2560, Arduino Leonardo, SparkFun Pro Micro, Arduino Micro, Arduino Pro Mini 3.3 V, ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, Raspberry Pi Pico, Raspberry Pi Pico W, Arduino Nano RP2040 Connect, Seeed XIAO RP2040, Waveshare RP2040-Zero, Arduino Uno R4, Arduino Uno R4 WiFi.

In Mokxi it is built in: #include <Adafruit_NeoMatrix.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "Adafruit NeoMatrix" by Adafruit from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add Adafruit NeoMatrix to lib_deps in PlatformIO. Mokxi follows the calls of release 1.3.3, so a sketch written here builds there too.

What to know in the simulator: Color() packs a 5-6-5 color; a drawn pixel is widened to eight bits per channel through a gamma curve of 2.5, Mokxi’s own, so a middle shade can differ from upstream’s by a step or two. The boards are Adafruit_NeoPixel’s.

- Arduino Uno
- Arduino Nano
- Arduino Mega 2560
- Arduino Leonardo
- SparkFun Pro Micro
- Arduino Micro
- Arduino Pro Mini 3.3 V
- ESP32-C3
- ESP32-C6
- Seeed XIAO ESP32-C3
- ESP32-C3 SuperMini
- Seeed XIAO ESP32-C6
- ESP32 DevKit
- ESP32-DevKitC V4
- LOLIN32 Lite
- Wemos D1 R32
- Cheap Yellow Display
- TTGO T-Display
- ESP32-S3-DevKitC-1
- Seeed XIAO ESP32-S3
- Arduino Nano ESP32
- Raspberry Pi Pico
- Raspberry Pi Pico W
- Arduino Nano RP2040 Connect
- Seeed XIAO RP2040
- Waveshare RP2040-Zero
- Arduino Uno R4
- Arduino Uno R4 WiFi

## The calls you will use

In the order a sketch meets them.

### Adafruit_NeoMatrix matrix(8, 8, 6, NEO_MATRIX_TOP + NEO_MATRIX_LEFT + NEO_MATRIX_ROWS + NEO_MATRIX_ZIGZAG, NEO_GRB + NEO_KHZ800)

An 8x8 panel on pin 6, LED 0 at the top left, wired in rows that turn back at each end. The last argument is the strip type, as for Adafruit_NeoPixel.

### matrix.begin()

Sets the data pin up. Call it once in setup().

### matrix.setBrightness(40)

Scales every color down, 0 to 255. Keep it low: a 16x16 panel at full white draws far more current than a USB port supplies.

### matrix.Color(255, 0, 0)

Packs red, green and blue into the 16-bit color the drawing calls take.

### matrix.drawRect(2, 2, 4, 4, matrix.Color(255, 0, 0))

A GFX rectangle outline at (2, 2), four by four. Any Adafruit_GFX shape works the same way.

### matrix.print("M")

Prints text at the cursor in the 5x7 GFX font. setTextWrap(false) and a moving setCursor() make scrolling text.

### matrix.show()

Sends the colors to the LEDs. Nothing changes on the panel until this runs.

### matrix.setRemapFunction(myRemap)

Replaces the layout flags with your own function from (x, y) to LED number, for panels wired in an unusual order.

## Example: A border and a letter on a 16 x 16 panel

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3

### Wiring

- Arduino Uno R3 6 to Addressable RGB LEDs DIN
- Arduino Uno R3 5V to Addressable RGB LEDs VDD
- Arduino Uno R3 GND to Addressable RGB LEDs VSS

Open it in the editor, wired and ready to run

## Common errors and how to fix them

### Every other row is drawn backward, so shapes look torn

The panel is wired zigzag and the sketch says PROGRESSIVE. Change NEO_MATRIX_PROGRESSIVE to NEO_MATRIX_ZIGZAG; if the picture is then mirrored, change the corner flags too.

### The picture is rotated a quarter turn

The strip runs down the columns, not along the rows. Use NEO_MATRIX_COLUMNS, or call setRotation() to turn the drawing to match how the panel is mounted.

### 'Adafruit_NeoMatrix' does not name a type, or errors from inside Adafruit_GFX

All three headers are needed, in this order: Adafruit_GFX.h, Adafruit_NeoMatrix.h, Adafruit_NeoPixel.h. Add whichever is missing at the top of the sketch.

## Keep going

### Learn

- Arduino NeoPixel (WS2812B): Wiring and Code
- ESP32 NeoPixel (WS2812B) Rainbow Tutorial

### Parts

- Addressable RGB LEDs

### More leds libraries

- Arduino_LED_Matrix (Uno R4 core)
- Adafruit NeoPixel
- FastLED
- NeoPixelBus by Makuna
- WS2812FX
- Adafruit DotStar

Every built-in library · Open the editor

## Try Adafruit NeoMatrix without installing anything

Open the example, change the sketch, and keep your version in a free account.

Start building free

Open the editor