Matrix Image

Convert any image into a grayscale LED dot matrix display with per-pixel opacity and adjustable resolution.

Installation

File Structure

matrix-image.tsx

Usage

import {
  MatrixImage,
  imageToMatrix,
  fileToMatrix,
  srcToMatrix,
} from "@/components/unlumen-ui/matrix-image"

// From a URL
<MatrixImage src="/my-photo.jpg" rows={48} cols={48} size={4} gap={1} />

// From pre-computed data
const frame = await srcToMatrix("/photo.jpg", 32, 32)
<MatrixImage data={frame} rows={32} cols={32} />

// From a file input
const file = event.target.files[0]
const frame = await fileToMatrix(file, 64, 64)
<MatrixImage data={frame} rows={64} cols={64} />

API Reference

MatrixImage

PropTypeDefault
src?
string
-
data?
Frame
-
rows?
number
32
cols?
number
32
size?
number
6
gap?
number
2
palette?
{ on: string; off: string }
-
brightness?
number
1
invert?
boolean
false
ariaLabel?
string
"matrix image"
className?
string
-

Utility functions

// Convert an HTMLImageElement or HTMLCanvasElement to a Frame
imageToMatrix(image: HTMLImageElement | HTMLCanvasElement, rows: number, cols: number, invert?: boolean): Frame

// Convert a File object to a Frame (async)
fileToMatrix(file: File, rows: number, cols: number, invert?: boolean): Promise<Frame>

// Convert an image URL to a Frame (async)
srcToMatrix(src: string, rows: number, cols: number, invert?: boolean): Promise<Frame>

Notes

The component uses the existing Matrix component under the hood, converting images to grayscale brightness values via a hidden canvas. Each pixel is sampled using the BT.601 luma formula (0.299R + 0.587G + 0.114B) and respects alpha transparency.

By default, dark areas in the image produce bright dots (like an LED display). Set invert to reverse this behavior.

For best results, use images with good contrast. The size prop auto-scales based on resolution — higher resolutions work well with smaller dot sizes.

Credits

From ui.elevenlabs/matrix adapted by me for image rendering.