API Reference · 2 min read

DotMatrix API

Complete API reference for the DotMatrix component

DotMatrix API

Complete API reference for the DotMatrix component.

Import

import { DotMatrix } from "dot-anime-react";
import type { DotMatrixConfig, DotMatrixProps } from "dot-anime-react";

Props

Prop	Type	Default	Description
`sequence`*	`number[][]`	-	Array of animation frames. Each frame is an array of dot indices that should be active during that frame.
`cols`	`number`	7	Number of columns in the dot grid.
`rows`	`number`	7	Number of rows in the dot grid.
`dotSize`	`number`	8	Size of each dot in pixels.
`gap`	`number`	4	Gap between dots in pixels.
`interval`	`number`	100	Time between frame transitions in milliseconds.
`shape`	`'rounded' \| 'square' \| 'circle'`	'rounded'	Visual shape of each dot.
`color`	`string`	'#10b981'	Color of active (lit) dots.
`inactiveColor`	`string`	'rgba(16, 185, 129, 0.1)'	Color of inactive dots.
`activeDotStyle`	`CSSProperties`	-	Additional CSS styles applied to active dots.
`inactiveDotStyle`	`CSSProperties`	-	Additional CSS styles applied to inactive dots.
`style`	`CSSProperties`	-	CSS styles applied to the container element.
`className`	`string`	-	CSS class name for the container element.

Types

DotMatrixConfig

Configuration type for DotMatrix (excludes sequence):

type DotMatrixConfig = Omit<DotMatrixProps, "sequence">;

DotMatrixProps

Full props type including all HTML div attributes:

interface DotMatrixProps extends HTMLAttributes<HTMLDivElement> {
  sequence: number[][];
  cols?: number;
  rows?: number;
  dotSize?: number;
  gap?: number;
  interval?: number;
  shape?: "rounded" | "square" | "circle";
  color?: string;
  inactiveColor?: string;
  activeDotStyle?: CSSProperties;
  inactiveDotStyle?: CSSProperties;
}

Index Calculation

To calculate the index of a dot at position (row, col):

const index = row * cols + col;

// Examples for a 7x7 grid:
// (0, 0) -> 0  (top-left)
// (3, 3) -> 24 (center)
// (6, 6) -> 48 (bottom-right)

Animation Behavior

The component cycles through frames in the sequence array
Each frame displays for the duration specified by interval
Animation loops continuously
Frame changes are instant (no transition)