Dot Anime React

https://dotanime.dev/docs
Admin
Lightweight dot matrix animation components for React with zero dependencies, a small gzipped size,...
Tokens:7,261
Snippets:72
Trust Score:3.1
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install dot-anime-react using npm, yarn, or pnpm

Source: https://dotanime.dev/docs/getting-started/installation

Install the dot-anime-react library using your preferred package manager. This makes the library's components available for use in your project. Ensure you have Node.js 16+ and React 18+ installed.

```bash
npm install dot-anime-react
```

```bash
yarn add dot-anime-react
```

```bash
pnpm add dot-anime-react
```

--------------------------------

### Import dot-anime-react Components

Source: https://dotanime.dev/docs/getting-started/installation

Import the necessary components like DotMatrix, ScrambleText, or DotFlow from the 'dot-anime-react' library after installation. These components are tree-shakeable, meaning only the used components are bundled.

```javascript
import { DotMatrix, ScrambleText, DotFlow } from "dot-anime-react";
```

--------------------------------

### DotMatrix Loading Animation Example

Source: https://dotanime.dev/docs/components/dot-matrix

Provides a specific example of a 'Loading Animation' using the DotMatrix component. It defines a `loadingSequence` and renders the component with a custom interval.

```javascript
const loadingSequence = [
  [21, 22, 23],
  [22, 23, 24],
  [23, 24, 25],
  [24, 25, 26],
  [25, 26, 27],
  [24, 25, 26],
  [23, 24, 25],
  [22, 23, 24],
];

<DotMatrix
  sequence={loadingSequence}
  cols={7}
  rows={7}
  interval={100}
/>
```

--------------------------------

### Understanding Dot Matrix Grid Indexing

Source: https://dotanime.dev/docs/getting-started/quick-start

Explains the index-based grid system used by DotMatrix. Each dot has a unique index calculated by the formula: index = row * cols + col. This helps in defining animation frames.

```text
7x7 Grid Index 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   <- center
28  29  30  31  32  33  34
35  36  37  38  39  40  41
42  43  44  45  46  47  48

Formula: index = row * cols + col
```

--------------------------------

### Creating a Pulse Animation in React

Source: https://dotanime.dev/docs/getting-started/quick-start

Demonstrates how to create a pulse animation using the DotMatrix component from dot-anime-react. The animation is defined by a sequence of frames, where each frame is an array of active dot indices.

```jsx
import { DotMatrix } from "dot-anime-react";

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

function PulseAnimation() {
  return (
    <DotMatrix
      sequence={pulseSequence}
      cols={7}
      rows={7}
      dotSize={10}
      gap={5}
      interval={120}
      color="#34d399"
      inactiveColor="rgba(52, 211, 153, 0.1)"
    />
  );
}
```

--------------------------------

### Customizing DotMatrix Animation Speed (React)

Source: https://dotanime.dev/docs/getting-started/quick-start

Shows how to adjust the animation speed of the DotMatrix component by modifying the `interval` prop. A larger value results in a slower animation.

```jsx
<DotMatrix
  sequence={pulseSequence}
  interval={200}  // Slower animation
/>
```

--------------------------------

### DotFlow Vertical Layout Example

Source: https://dotanime.dev/docs/components/dot-flow

Illustrates how to configure DotFlow for a vertical layout. This example also shows adjusting the spacing between elements for better visual separation.

```jsx
<DotFlow
  items={items}
  direction="vertical"
  spacing={12}
/>
```

--------------------------------

### React ScrambleText Custom Characters Examples

Source: https://dotanime.dev/docs/components/scramble-text

Illustrates how to customize the scrambling characters for ScrambleText, showing binary, symbols, and Japanese Katakana examples.

```javascript
// Binary style
<ScrambleText
  text="Loading..."
  chars="01"
/>

// Symbols
<ScrambleText
  text="Processing"
  chars="!@#$%^&*()_+-=[]{}|;:,.<>?"
/>

// Japanese Katakana
<ScrambleText
  text="アニメーション"
  chars="アイウエオカキクケコサシスセソタチツテト"
/>
```

--------------------------------

### Import TypeScript Types for dot-anime-react

Source: https://dotanime.dev/docs/getting-started/installation

Import type definitions for configuration objects, such as DotMatrixConfig and ScrambleTextConfig, directly from the 'dot-anime-react' library. This provides type safety and autocompletion for TypeScript projects.

```typescript
import type { DotMatrixConfig, ScrambleTextConfig } from "dot-anime-react";
```

--------------------------------

### Adding Glow Effect to DotMatrix Dots (React)

Source: https://dotanime.dev/docs/getting-started/quick-start

Demonstrates how to add a glow effect to the active dots of the DotMatrix component by utilizing the `activeDotStyle` prop. This allows for custom CSS styling, such as box-shadow.

```jsx
<DotMatrix
  sequence={pulseSequence}
  color="#34d399"
  activeDotStyle={{
    boxShadow: "0 0 10px #34d39980",
  }}
/>
```

--------------------------------

### React ScrambleText Callback Example

Source: https://dotanime.dev/docs/components/scramble-text

Demonstrates how to use the onComplete callback prop in ScrambleText to execute a function once the animation finishes.

```javascript
<ScrambleText
  text="Complete"
  onComplete={() => console.log("Animation finished!")}
/>
```

--------------------------------

### Customizing DotMatrix Colors (React)

Source: https://dotanime.dev/docs/getting-started/quick-start

Illustrates how to change the active and inactive dot colors for the DotMatrix component using the `color` and `inactiveColor` props. Supports hexadecimal color codes and RGBA values.

```jsx
<DotMatrix
  sequence={pulseSequence}
  color="#60a5fa"           // Active dot color
  inactiveColor="#60a5fa20" // Inactive dot color (with alpha)
/>
```

--------------------------------

### DotMatrix Glow Effect Example

Source: https://dotanime.dev/docs/components/dot-matrix

Illustrates how to add a glow effect to the active dots in a DotMatrix animation using the `activeDotStyle` prop. This example applies a box shadow to the dots.

```javascript
<DotMatrix
  sequence={sequence}
  color="#34d399"
  activeDotStyle={{
    boxShadow: "0 0 10px #34d39980",
  }}
/>
```

--------------------------------

### React ScrambleText Styling Example

Source: https://dotanime.dev/docs/components/scramble-text

Illustrates how to apply standard HTML attributes, className, and inline styles to the ScrambleText component for custom styling.

```javascript
<ScrambleText
  text="Styled Text"
  className="text-2xl font-bold text-emerald-400"
  style={{ letterSpacing: "0.1em" }}
/>
```

--------------------------------

### React ScrambleText Controlled Animation Example

Source: https://dotanime.dev/docs/components/scramble-text

Shows how to control the ScrambleText animation dynamically using React's useState hook to update the text prop.

```javascript
import { useState } from "react";

function ControlledScramble() {
  const [text, setText] = useState("Initial");

  return (
    <div>
      <ScrambleText text={text} />
      <button onClick={() => setText("Updated!")}>
        Change Text
      </button>
    </div>
  );
}
```

--------------------------------

### ScrambleText Character Set Presets

Source: https://dotanime.dev/docs/api/scramble-text

Provides examples of predefined character sets that can be used with the ScrambleText component. These include alphanumeric, binary, symbols, and Katakana character sets, allowing for diverse visual effects.

```javascript
// Alphanumeric (default)
const alphanumeric = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";

// Binary
const binary = "01";

// Symbols
const symbols = "!@#$%^&*()_+-=[]{}|;:,.<>?";

// Katakana
const katakana = "アイウエオカキクケコサシスセソタチツテトナニヌネノ";
```

--------------------------------

### DotMatrix Shape Variations

Source: https://dotanime.dev/docs/components/dot-matrix

Demonstrates how to change the shape of the dots in the DotMatrix animation. It shows examples for the default 'rounded' shape, 'square', and 'circle'.

```javascript
// Rounded corners (default)
<DotMatrix shape="rounded" />

// Square dots
<DotMatrix shape="square" />

// Circle dots
<DotMatrix shape="circle" />
```

--------------------------------

### Controlled DotFlow Mode in React

Source: https://dotanime.dev/docs/components/dot-flow

Provides an example of implementing controlled mode for DotFlow using React's useState hook. This allows external control over the active item and handles changes via a callback.

```jsx
import { useState } from "react";

function ControlledDotFlow() {
  const [index, setIndex] = useState(0);

  return (
    <div>
      <DotFlow
        items={items}
        activeIndex={index}
        onChange={setIndex}
      />
      <div>
        {items.map((_, i) => (
          <button key={i} onClick={() => setIndex(i)}>
            {i + 1}
          </button>
        ))}
      </div>
    </div>
  );
}
```

--------------------------------

### Uncontrolled DotFlow Usage Example - JSX

Source: https://dotanime.dev/docs/api/dot-flow

Demonstrates the uncontrolled mode of the DotFlow component, where it manages its active state internally. The 'autoPlay' prop is used to automatically cycle through items at a specified interval.

```jsx
<DotFlow
  items={items}
  autoPlay={2000}  // Rotates every 2 seconds
/>
```

--------------------------------

### React ScrambleText Disable Animation Example

Source: https://dotanime.dev/docs/components/scramble-text

Shows how to disable the scramble animation of the ScrambleText component by setting the animate prop to false.

```javascript
<ScrambleText
  text="No animation"
  animate={false}
/>
```

--------------------------------

### Calculate Dot Index

Source: https://dotanime.dev/docs/api/dot-matrix

Provides a formula to calculate the linear index of a dot within a grid based on its row and column. This is a fundamental calculation for positioning and managing dots in the DotMatrix component. Examples for a 7x7 grid are included.

```javascript
const index = row * cols + col;

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

--------------------------------

### DotMatrixProps Type Definition

Source: https://dotanime.dev/docs/api/dot-matrix

Defines the complete type for DotMatrix component props, including all standard HTML div attributes. This interface specifies the expected data types and optionality for each prop, guiding developers on how to configure the component.

```typescript
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;
}
```

--------------------------------

### Controlled DotFlow Usage Example - JSX

Source: https://dotanime.dev/docs/api/dot-flow

Illustrates the controlled mode of the DotFlow component, where the active item index is managed externally using React's 'useState' hook. The 'activeIndex' prop dictates the current item, and 'onChange' allows updating the external state.

```jsx
const [index, setIndex] = useState(0);

<DotFlow
  items={items}
  activeIndex={index}
  onChange={setIndex}
/>
```

--------------------------------

### DotMatrix Basic Usage

Source: https://dotanime.dev/docs/components/dot-matrix

Demonstrates the fundamental usage of the DotMatrix component with a predefined sequence, grid dimensions, and styling properties. It imports the component and defines a sample animation sequence.

```javascript
import { DotMatrix } from "dot-anime-react";

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

<DotMatrix
  sequence={sequence}
  cols={7}
  rows={7}
  dotSize={10}
  gap={5}
  interval={120}
  color="#34d399"
/>
```

--------------------------------

### Basic DotFlow Usage in React

Source: https://dotanime.dev/docs/components/dot-flow

Demonstrates the fundamental implementation of the DotFlow component. It requires an array of items, each with a title and animation frames. The component can be configured with autoplay and direction.

```jsx
import { DotFlow } from "dot-anime-react";

const items = [
  {
    title: "Loading",
    frames: [[24], [17, 23, 25, 31], [24]],
  },
  {
    title: "Processing",
    frames: [[21, 22, 23], [22, 23, 24], [23, 24, 25]],
  },
  {
    title: "Complete",
    frames: [[16, 18, 30, 32], [24]],
  },
];

<DotFlow
  items={items}
  autoPlay={2000}
  direction="horizontal"
/>
```

--------------------------------

### DotMatrix Component Props

Source: https://dotanime.dev/docs/api/dot-matrix

This section details the available props for configuring the DotMatrix component, including their types, default values, and descriptions.

```APIDOC
## DotMatrix Component Props

This section details the available props for configuring the DotMatrix component, including their types, default values, and descriptions.

### Props Table

| 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):

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

#### DotMatrixProps

Full props type including all HTML div attributes:

```typescript
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):

```javascript
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)
```

--------------------------------

### React ScrambleText Basic Usage

Source: https://dotanime.dev/docs/components/scramble-text

Demonstrates the fundamental implementation of the ScrambleText component, setting the text content and animation timing.

```javascript
import { ScrambleText } from "dot-anime-react";

<ScrambleText
  text="Hello World"
  duration={400}
  interval={30}
/>
```

--------------------------------

### Import DotMatrix Component and Types

Source: https://dotanime.dev/docs/api/dot-matrix

Imports the main DotMatrix component and necessary types for its configuration and properties from the 'dot-anime-react' library. These are essential for using the component in your React application.

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

--------------------------------

### Import ScrambleText Component and Types

Source: https://dotanime.dev/docs/api/scramble-text

Imports the ScrambleText component and its associated configuration and props types from the 'dot-anime-react' library. These are necessary for using the component in your React application.

```typescript
import { ScrambleText } from "dot-anime-react";
import type { ScrambleTextConfig, ScrambleTextProps } from "dot-anime-react";
```

--------------------------------

### DotFlow Custom Text Styling

Source: https://dotanime.dev/docs/components/dot-flow

Demonstrates how to apply custom styling to the text elements within the DotFlow component. Options include font size, color, and weight.

```jsx
<DotFlow
  items={items}
  textSize={24}
  textColor="#fbbf24"
  textWeight={700}
/>
```

--------------------------------

### Import DotFlow Component and Types - TypeScript

Source: https://dotanime.dev/docs/api/dot-flow

Imports the main DotFlow component and its associated configuration and prop types from the 'dot-anime-react' library. These are essential for using DotFlow in a TypeScript project.

```typescript
import { DotFlow } from "dot-anime-react";
import type { DotFlowConfig, DotFlowProps, DotFlowItem } from "dot-anime-react";
```

--------------------------------

### DotFlow Custom Matrix Configuration

Source: https://dotanime.dev/docs/components/dot-flow

Shows how to customize the appearance and behavior of the DotMatrix within the DotFlow component. This includes setting dimensions, dot size, gap, and colors.

```jsx
<DotFlow
  items={items}
  matrix={{
    cols: 5,
    rows: 5,
    dotSize: 6,
    gap: 3,
    color: "#60a5fa",
    inactiveColor: "#60a5fa20",
  }}
/>
```

--------------------------------

### DotMatrixConfig Type Definition

Source: https://dotanime.dev/docs/api/dot-matrix

Defines a configuration type for the DotMatrix component, which is derived from DotMatrixProps but excludes the 'sequence' prop. This is useful for scenarios where you want to configure the component's appearance and behavior without providing the animation frames.

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

--------------------------------

### ScrambleText Component Props

Source: https://dotanime.dev/docs/api/scramble-text

Defines the properties available for the ScrambleText component. These include the text to animate, animation duration and interval, character set, animation control, completion callback, and styling options.

```typescript
interface ScrambleTextProps extends HTMLAttributes<HTMLSpanElement> {
  text: string;
  duration?: number;
  interval?: number;
  chars?: string;
  animate?: boolean;
  onComplete?: () => void;
}
```

--------------------------------

### DotMatrix Component - dot-anime-react

Source: https://dotanime.dev/docs/getting-started/introduction

The core DotMatrix component for creating dot matrix animations. It allows defining a grid of dots and animating them using provided frame sequences. This component is a fundamental part of the dot-anime-react library.

```jsx
import { DotMatrix } from "dot-anime-react";

<DotMatrix
  sequence={[[24], [17, 23, 25, 31]]}
  cols={7}
  rows={7}
/>
```

--------------------------------

### ScrambleTextConfig Type Definition

Source: https://dotanime.dev/docs/api/scramble-text

Defines the ScrambleTextConfig type, which is an alias for ScrambleTextProps excluding the 'text' prop. This is useful for configuring the animation without specifying the text content.

```typescript
type ScrambleTextConfig = Omit<ScrambleTextProps, "text">;
```

--------------------------------

### DotFlowConfig Interface Definition - TypeScript

Source: https://dotanime.dev/docs/api/dot-flow

Defines the configuration object for the DotFlow component, including item data, playback controls, layout options, and styling for the matrix and text.

```typescript
interface DotFlowConfig {
  items: DotFlowItem[];
  activeIndex?: number;
  autoPlay?: number;
  direction?: "horizontal" | "vertical";
  spacing?: number;
  matrix?: Omit<DotMatrixConfig, "sequence">;
  scramble?: Omit<ScrambleTextConfig, "text">;
  textSize?: number | string;
  textColor?: string;
  textWeight?: number | string;
  letterSpacing?: number | string;
  textStyle?: CSSProperties;
  onChange?: (index: number) => void;
}
```

--------------------------------

### DotFlow Custom Scramble Effect

Source: https://dotanime.dev/docs/components/dot-flow

Shows how to customize the scramble effect applied to the text in DotFlow. This includes adjusting the duration, interval between character scrambles, and the character set used.

```jsx
<DotFlow
  items={items}
  scramble={{
    duration: 500,
    interval: 40,
    chars: "01",
  }}
/>
```

--------------------------------

### ScrambleText Component - dot-anime-react

Source: https://dotanime.dev/docs/getting-started/introduction

The ScrambleText component provides a scramble/decode text animation effect. It's useful for dynamic text displays where changes should be visually engaging. The duration of the scramble effect can be customized.

```jsx
import { ScrambleText } from "dot-anime-react";

<ScrambleText text="Hello World" duration={400} />
```

--------------------------------

### DotFlow Component - dot-anime-react

Source: https://dotanime.dev/docs/getting-started/introduction

The DotFlow component is an advanced component that integrates DotMatrix and ScrambleText. It's designed for creating flowing, multi-item animations, suitable for sequences like loading or processing indicators. It supports autoplay functionality with a configurable delay.

```jsx
import { DotFlow } from "dot-anime-react";

<DotFlow
  items={[
    { title: "Loading", frames: [...] },
    { title: "Processing", frames: [...] },
  ]}
  autoPlay={2000}
/>
```

--------------------------------

### DotFlowItem Type Definition

Source: https://dotanime.dev/docs/components/dot-flow

Defines the structure of the `DotFlowItem` object required by the DotFlow component. Each item must have a `title` (string) and `frames` (a 2D array of numbers representing animation frames).

```typescript
interface DotFlowItem {
  title: string;      // Text to display
  frames: number[][]; // Animation frames for this item
}
```

--------------------------------

### DotFlowItem Interface Definition - TypeScript

Source: https://dotanime.dev/docs/api/dot-flow

Defines the structure for individual items within the DotFlow component. Each item must have a 'title' for display and 'frames' representing the animation data for the DotMatrix.

```typescript
interface DotFlowItem {
  /** Display title for this item */
  title: string;
  /** Animation frames for the DotMatrix */
  frames: number[][];
}
```

--------------------------------

### DotFlowProps Type Definition - TypeScript

Source: https://dotanime.dev/docs/api/dot-flow

Defines the props for the DotFlow component by extending DotFlowConfig and incorporating standard HTML div attributes. This allows for flexible customization and integration.

```typescript
type DotFlowProps = DotFlowConfig & Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange">;
```
Tokens:
Raw