react-dots

A context-aware, image-sampling geometric matrix for React. Renders an image as a grid of dots by sampling pixel data on an off-screen canvas, with a staggered wave animation. Degrades to a matte monochrome grid on load failure or CORS.

Install

npm install react-dots

Usage

import { Dots } from 'react-dots';

<Dots
  src="https://example.com/image.jpg"
  gridSize={20}
  width={400}
  height={400}
  dotRadius={3}
  duration={1200}
  crossOrigin="anonymous"
/>

Image sampling

• src — Image URL. If missing, invalid, or CORS-blocked, the component falls back to a stark monochrome dot grid.
• gridSize — Number of sampling steps per axis (e.g. 16 → 16×16 grid). Higher values = more detail and more dots.
• crossOrigin — Set to "anonymous" (or "use-credentials") when the image is from another origin so the canvas is not tainted and pixel sampling works.

Layout and animation

• width / height — Component size in pixels.
• dotRadius — Radius of each dot in pixels.
• duration — Full animation cycle duration in ms.
• easing — CSS easing (default: cubic-bezier(0.4, 0, 0.2, 1)).

Styling

• className — Applied to the wrapper div.
• style — Inline styles for the wrapper.

API summary

| Prop | Type | Default | Description | |-------------|--------|---------|--------------------------------------| | src | string | null | null | Image URL to sample | | gridSize | number | 16 | Grid density (dots per row/column) | | width | number | 320 | Component width (px) | | height | number | 320 | Component height (px) | | dotRadius | number | 3 | Dot radius (px) | | duration | number | 1200 | Animation cycle (ms) | | easing | string | cubic-bezier(…) | Animation easing | | crossOrigin | string | "anonymous" | Image CORS mode |

Build and publish

# Install dependencies
npm install

# Build the library (output in dist/)
npm run build

# Publish to npm (ensure you're logged in: npm login)
npm publish

For scoped packages (e.g. @your-org/react-dots), use:

npm publish --access public

License

MIT