rgb-split-image

rgb-split-image

A lightweight React component for adding interactive RGB split (chromatic aberration) effects to images.

• Zero dependencies
• SSR-safe
• Fully typed with strict TypeScript support
• React only (Works with Next.js, Remix, React,Gatsby )

⚠️ Epilepsy Warning:

try not to get a seizure while using this component.

Install

npm install rgb-split-image

Quick Start

import { RGBSplitImage } from "rgb-split-image";

<RGBSplitImage
  src="/hero.jpg"
  alt="Hero"
  idleEffect="breathe"
  splitDistance={10}
/>;

Drop it in, pick an effect, and you’re good to go.

Available Effects

Effect	What it does
none	No channel split everything stays aligned
breathe	Subtle, looping sine-wave motion
followMouse	Channels shift toward the cursor
glitch	Fast, random displacement each frame

Triggers

Effects can run in different states:

Prop	When it runs
idleEffect	Default state (always active unless overridden)
onHover	While hovering the image
onClick	Once per click, for effectDuration ms
onMount	Once when the component mounts

Priority order: onClick / onMount → onHover → idleEffect

Higher-priority effects temporarily override lower ones.

Props

Prop	Type	Default	Description
src	string	-	Image URL
alt	string	-	Alt text (required for accessibility)
idleEffect	RGBEffect	"none"	Default effect
onHover	RGBEffect	"none"	Effect on hover
onClick	RGBEffect	"none"	Effect on click
onMount	RGBEffect	-	Effect on mount
splitDistance	number	40	Max pixel distance channels can separate
effectDuration	number	1000	Duration of temporary effects (ms)
effectIntensity	number	1.5	Multiplier for temporary effects
breatheSpeed	number	1.0	Speed of the breathe animation
colorSpace	"rgb" | "cmyk"	"rgb"	Color matrix mode
grayscale	boolean	false	Desaturates the base image
trackWindowMouse	boolean	false	Track cursor outside the image bounds
disableOnMobile	boolean	false	Disable effects on viewports ≤ 768px
as	ElementType	"img"	Render as a custom component (e.g. Next.js Image)
onImageClick	MouseEventHandler	—	Native click handler

Type Safety

Some props (like breatheSpeed, effectDuration, effectIntensity, and trackWindowMouse) are conditionally typed.

If you pass them without activating the relevant effect, TypeScript will throw an error. No silent misconfiguration.

Examples

Breathe by default, glitch on click

<RGBSplitImage
  src="/photo.jpg"
  idleEffect="breathe"
  breatheSpeed={0.75}
  onClick="glitch"
  effectDuration={400}
  effectIntensity={1}
  splitDistance={20}
/>

Grayscale base with color following the cursor

<RGBSplitImage
  src="/landscape.jpg"
  idleEffect="followMouse"
  grayscale
  splitDistance={15}
/>

Track mouse across the whole window

<RGBSplitImage
  src="/grid.jpg"
  idleEffect="followMouse"
  trackWindowMouse
  splitDistance={20}
/>

Accessibility

• Automatically respects prefers-reduced-motion
• Pauses when out of view (via IntersectionObserver)
• Optional disableOnMobile to reduce battery usage
• Duplicate channel layers are marked aria-hidden="true"

License

MIT Jafar Sabaouni