Awesome Crossfade Grid Carousel

A React carousel that reveals the next slide through a tiled grid dissolve, with optional CRT-style flicker and multiple transition patterns. It supports local data or remote JSON and ships as a library-ready component.

Watch the demo here

Installation

npm install awesome-crossfade-grid-carousel

Styles

import 'awesome-crossfade-grid-carousel/style.css'

Peer dependencies:

• react ^18 || ^19
• react-dom ^18 || ^19

JSX Example

import { AwesomeCrossfadeGridCarousel } from "awesome-crossfade-grid-carousel";

const slides = [
  {
    id: 1,
    title: "Aurora Ridge",
    subtitle: "Lofoten, Norway",
    tag: "ARCTIC",
    body: "Crimson cabins cling to rock above mirror-still fjords.",
    stat: "02°",
    statLabel: "AVERAGE TEMP",
    accent: "#34d399",
    bg: "#071a12",
    imageUrl:
      "https://images.unsplash.com/photo-1531366936337-7c912a4589a7?w=1600&q=80",
  },
  {
    id: 2,
    title: "Desert Light",
    subtitle: "Sahara, Morocco",
    tag: "DESERT",
    body: "A sea of sculpted dunes that shifts overnight.",
    accent: "#fbbf24",
    bg: "#1c1007",
    imageUrl:
      "https://images.unsplash.com/photo-1509316785289-025f5b846b35?w=1600&q=80",
  },
];

export default function App() {
  return (
    <AwesomeCrossfadeGridCarousel
      data={slides}
      gridCols={8}
      gridRows={6}
      autoInterval={4800}
      cellDuration={380}
      staggerSpread={600}
      patterns={["wave", "scatter", "radial", "blinds", "spiral"]}
    />
  );
}

Props

AwesomeCrossfadeGridCarousel Props

| Prop | Type | Default | Description | | --------------- | ------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------- | | data | GridSlide[] | [] | Local slides data. Prefer this or apiEndpoint. | | apiEndpoint | string | undefined | URL returning GridSlide[] or { data: GridSlide[] }. | | apiHeaders | Record<string, string> | undefined | Headers for the remote request. | | apiTransform | (raw: unknown) => GridSlide[] | undefined | Transform API response into slides. | | gridCols | number | 8 | Number of columns in the grid. | | gridRows | number | 6 | Number of rows in the grid. | | autoInterval | number | 4000 | Auto-advance interval (ms). | | cellDuration | number | 360 | Duration of each cell fade (ms). | | staggerSpread | number | 580 | Maximum stagger delay across cells (ms). | | flicker | boolean | true | Enables CRT-style flicker during fades. | | patterns | PatternMode[] | ['wave','scatter','radial','blinds','spiral'] | Pattern cycle order. | | onSlideClick | (slide: GridSlide) => void | undefined | Global click fallback for slides. | | onSlideChange | (index: number, slide: GridSlide) => void | undefined | Called after the slide changes. |

GridSlide Type

| Field | Type | Required | Description | | ----------- | ---------------------------- | -------- | -------------------------------- | | id | number | Yes | Unique slide ID. | | title | string | Yes | Main headline. | | subtitle | string | No | Supporting line under the title. | | tag | string | No | Small uppercase label. | | body | string | No | Body copy shown near the bottom. | | stat | string | No | Large stat number or highlight. | | statLabel | string | No | Label under the stat. | | accent | string | Yes | Accent color (hex recommended). | | bg | string | Yes | Fallback background color. | | imageUrl | string | No | Full-bleed background image. | | textColor | string | No | Override text color. | | onClick | (slide: GridSlide) => void | No | Per-slide click handler. |

Pattern Modes

PatternMode can be: wave, scatter, radial, blinds, spiral.

License

MIT