API Reference · 3 min read

DotFlow API

Complete API reference for the DotFlow component

DotFlow API

Complete API reference for the DotFlow component.

Import

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

Props

Prop	Type	Default	Description
`items`*	`DotFlowItem[]`	-	Array of items to cycle through. Each item has a title and frames.
`activeIndex`	`number`	-	Controlled mode: current active item index.
`autoPlay`	`number`	-	Auto-rotate interval in milliseconds. Omit to disable auto-rotation.
`direction`	`'horizontal' \| 'vertical'`	'horizontal'	Layout direction of the component.
`spacing`	`number`	16	Gap between the dot matrix and text in pixels.
`matrix`	`DotMatrixConfig`	-	Configuration passed to the internal DotMatrix component.
`scramble`	`ScrambleTextConfig`	-	Configuration passed to the internal ScrambleText component.
`textSize`	`number \| string`	16	Font size of the title text.
`textColor`	`string`	-	Color of the title text. Defaults to matrix color.
`textWeight`	`number \| string`	500	Font weight of the title text.
`letterSpacing`	`number \| string`	-	Letter spacing of the title text.
`textStyle`	`CSSProperties`	-	Additional styles for the title text (highest priority).
`onChange`	`(index: number) => void`	-	Callback fired when the active index changes.

Types

DotFlowItem

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

DotFlowConfig

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

DotFlowProps

Extends DotFlowConfig with HTML div attributes:

type DotFlowProps = DotFlowConfig & Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange">;

Controlled vs Uncontrolled

Uncontrolled (with autoPlay)

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

Controlled

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

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

Behavior

In uncontrolled mode with autoPlay, cycles through items automatically
In controlled mode, responds to activeIndex prop changes
ScrambleText animates when the active item changes
DotMatrix displays the frames of the current active item