Skip to content

IveTian/dot-anime-react

Repository files navigation

🔲 dot-anime-react

Lightweight React dot matrix animation components

npm version npm downloads bundle size license [CodeRabbit Pull Request Reviews] Features · Installation · Quick Start · Components · API


Features

  • 🎯 Zero Dependencies — Pure React implementation, no external libraries
  • 🪶 Lightweight — Less than 3KB gzipped
  • 🎨 Highly Customizable — Colors, shapes, sizes, and timing all configurable
  • 📦 TypeScript Ready — Full type definitions included
  • 🔄 Frame-based Animation — Simple and intuitive animation format
  • Performant — Optimized rendering with minimal re-renders

Installation

npm install dot-anime-react
yarn add dot-anime-react
pnpm add dot-anime-react

Quick Start

import { DotMatrix } from 'dot-anime-react';

const sequence = [
  [24],
  [17, 23, 25, 31],
  [10, 16, 18, 24, 30, 32, 38],
  [17, 23, 25, 31],
  [24],
];

function App() {
  return <DotMatrix sequence={sequence} />;
}

That's it! The component renders a 7×7 dot grid and animates through the frames automatically.


Components

DotMatrix

The core component for rendering dot matrix animations.

<DotMatrix
  sequence={sequence}
  cols={7}
  rows={7}
  dotSize={8}
  gap={3}
  shape="circle"
  interval={100}
  color="#00ffff"
  inactiveColor="#222"
/>

Understanding Frame Sequences

Each frame is an array of dot indices to activate. Index is calculated as row × cols + column:

7×7 Grid Layout:
 0  1  2  3  4  5  6
 7  8  9 10 11 12 13
14 15 16 17 18 19 20
21 22 23 24 25 26 27
28 29 30 31 32 33 34
35 36 37 38 39 40 41
42 43 44 45 46 47 48

Shape Options

<DotMatrix shape="circle" />   // ● Round dots
<DotMatrix shape="square" />   // ■ Square dots
<DotMatrix shape="rounded" />  // ▢ Rounded squares (default)
<DotMatrix radius={4} />       // Custom border radius

Animation Control

const [playing, setPlaying] = useState(true);

<DotMatrix
  sequence={sequence}
  active={playing}           // Play/pause
  loop={3}                   // Loop count (-1 for infinite)
  onFrameChange={(i) => {}}  // Frame change callback
  onFinish={() => {}}        // Animation complete callback
/>

Custom Styling

<DotMatrix
  dotStyle={{ opacity: 0.3 }}
  activeDotStyle={{
    backgroundColor: '#0ff',
    boxShadow: '0 0 8px #0ff',
  }}
  bgColor="#000"
/>

ScrambleText

Text scramble transition effect, perfect for status labels.

import { ScrambleText } from 'dot-anime-react';

<ScrambleText
  text="Loading"
  duration={800}
  interval={30}
  chars="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
  onComplete={() => console.log('done')}
/>

When text prop changes, the component animates through random characters before settling on the new text.


DotFlow

A compound component combining DotMatrix and ScrambleText with auto-rotation support.

import { DotFlow } from 'dot-anime-react';

const items = [
  { title: "Loading", frames: [[24], [17,23,25,31], [24]] },
  { title: "Success", frames: [[30], [23,30,37], [16,23,30,37,44]] },
  { title: "Error",   frames: [[0,6,42,48], [8,12,36,40]] },
];

// Uncontrolled with auto-play
<DotFlow items={items} autoPlay={3000} />

// Controlled mode
const [index, setIndex] = useState(0);
<DotFlow items={items} activeIndex={index} onChange={setIndex} />

Configuration

<DotFlow
  items={items}
  direction="horizontal"  // or "vertical"
  spacing={16}
  matrix={{ dotSize: 8, shape: "circle", color: "#0ff" }}
  scramble={{ duration: 500 }}
  textSize={18}
  textColor="#0ff"
  textWeight={600}
/>

API Reference

DotMatrix Props

Prop Type Default Description
sequence number[][] required Animation frames (array of active dot indices)
cols number 7 Grid columns
rows number 7 Grid rows
dotSize number 6 Dot size in pixels
gap number 2 Gap between dots in pixels
shape "circle" | "square" | "rounded" "rounded" Dot shape preset
radius number | string Custom border radius (overrides shape)
interval number 100 Frame duration in ms
active boolean true Play/pause animation
loop number -1 Loop count (-1 = infinite)
color string "#ffffff" Active dot color
inactiveColor string "rgba(255,255,255,0.15)" Inactive dot color
bgColor string Container background
dotStyle CSSProperties Base dot styles
activeDotStyle CSSProperties Active dot styles (highest priority)
onFrameChange (index: number) => void Frame change callback
onFinish () => void Animation complete callback

Also accepts all HTMLDivElement attributes except children

ScrambleText Props

Prop Type Default Description
text string required Target text
chars string A-Z0-9 Character set for scramble effect
duration number 800 Animation duration in ms
interval number 30 Character update interval in ms
animate boolean true Enable/disable animation
onComplete () => void Animation complete callback

Also accepts all HTMLSpanElement attributes except children

DotFlow Props

Prop Type Default Description
items { title: string, frames: number[][] }[] required Animation items
activeIndex number Controlled mode index
autoPlay number Auto-rotation interval in ms
direction "horizontal" | "vertical" "horizontal" Layout direction
spacing number 16 Gap between matrix and text
matrix DotMatrixConfig DotMatrix props
scramble ScrambleTextConfig ScrambleText props
textSize number | string 16 Text font size
textColor string Text color (inherits from matrix.color)
textWeight number | string 500 Text font weight
letterSpacing number | string Text letter spacing
textStyle CSSProperties Custom text styles
onChange (index: number) => void Index change callback

Also accepts all HTMLDivElement attributes except children and onChange


TypeScript

Full type definitions are included:

import type {
  DotMatrixProps,
  DotMatrixConfig,
  DotShape,
  ScrambleTextProps,
  ScrambleTextConfig,
  DotFlowProps,
  DotFlowConfig,
  DotFlowItem,
} from 'dot-anime-react';

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © dot-anime-react

About

A lightweight React dot matrix animation component with zero dependencies

Topics

Resources

License

Contributing

Stars

Watchers

Forks

Packages

 
 
 

Contributors