AwesomeWaterWellGlassCarousel

A stunning 3D cylindrical Water Well carousel with Liquid Glass Morphism — built with React 19. Features continuous clockwise auto-rotation, three colour themes (purple, yellow, blue), dynamic blurred slide backgrounds, drag/swipe, keyboard navigation and an animated orbit ring. Built with React 19 · Zero UI dependencies ·

Features

• 3D Cylindrical Layout — Cards are positioned on a true CSS 3D cylinder using rotateY + translateZ with a deep perspective — like looking down into a water well
• Continuous Clockwise Rotation — Powered by requestAnimationFrame; the rotation never resets or jumps — always smooth, always forward
• Liquid Glass Morphism — backdrop-filter blur, layered gradients, inset borders, glow halos and a shine sweep overlay on every card
• Live Background — Each slide's image cross-fades as the full-screen blurred backdrop, colour-tinted by the active theme
• Three Themes — 🟣 Purple · 🟡 Yellow · 🔵 Blue, switchable live via CSS variables
• Click Events — onSlideClick(item, index) fires when the active card (or its ↗ button) is clicked
• Drag / Swipe — Grab and drag left/right anywhere on the stage to spin manually
• Keyboard Navigation — ← / → arrow keys
• Smart Pause — Auto-rotation pauses on hover, drag, or manual navigation; a pill badge lets users resume
• Orbit Ring — SVG orbit counter (bottom-right) with a continuously rotating glow dot in sync with the cylinder angle
• Data Flexibility — Pass a JS array, a REST API URL, or a local JSON file path; falls back to built-in demo data
• Fully Accessible — ARIA roles, aria-label, aria-selected, focus-visible outlines throughout

Installation

# npm
npm install awesome-water-well-glass-carousel

# yarn
yarn add awesome-water-well-glass-carousel

# pnpm
pnpm add awesome-water-well-glass-carousel

Quick Start

// 1. Import component + stylesheet
import { AwesomeWaterWellGlassCarousel } from "awesome-water-well-glass-carousel";
import "awesome-water-well-glass-carousel/style.css";

// 2. Drop it in
export default function App() {
  return <AwesomeWaterWellGlassCarousel />;
}

Peer requirements: React ≥ 18 and react-dom ≥ 18 must already be installed in your project.

Props

| Prop | Type | Default | Description | |-----------------|---------------------------|--------------|--------------------------------------------------------------------------------| | data | Array \| string \| null | null | Items array, fetch URL (REST / local JSON), or null to use built-in demo data | | theme | string | "purple" | Active colour theme. One of "purple", "yellow", "blue" | | autoPlay | boolean | true | Enable continuous clockwise auto-rotation | | interval | number | 3200 | Milliseconds for one full step when autoPlay is true | | onSlideClick | (item, index) => void | null | Callback fired when the active card (or its ↗ button) is clicked |

Item Data Shape

Each object in your data array should follow this shape:

| Field | Type | Required | Description | |-------------|--------------|----------|---------------------------------------------------------------| | id | any | No | Unique key. Falls back to array index if omitted | | title | string | Yes | Primary heading (rendered in Playfair Display serif) | | subtitle | string | No | Small uppercase tag line below the title | | price | string | Yes | Displayed prominently in the card footer | | image | string | Yes | Product image URL (shown inside the card) | | bg | string | No | Full-bleed background image URL. Falls back to image | | onAction | () => void | No | Legacy per-item callback on ↗ button click (use onSlideClick instead) |

Example

const products = [
  {
    id: 1,
    title:    "Apple Watch",
    subtitle: "Starlight Sport Band",
    price:    "139$",
    image:    "https://example.com/watch-thumb.jpg",
    bg:       "https://example.com/watch-full.jpg",
  },
  // …more items
];

Themes

The component ships with three built-in themes, each applied via CSS custom properties injected at the root element.

| Theme Name | Prop Value | Primary Colour | Glow Colour | Use Case | |------------|--------------|----------------|----------------|-----------------------------| | Purple | "purple" | #8a2be2 | rgb(180,100,255) | Default — elegant, luxury | | Yellow | "yellow" | #daa520 | rgb(255,210,50) | Warm, energetic, premium | | Blue | "blue" | #1e6eff | rgb(80,165,255) | Cool, tech, modern |

Themes affect: background overlay tint, card border glow, price text glow, CTA button colour, orbit ring dots, theme-switcher circles, and the well-fog gradient.

The user can also switch themes at runtime using the three dot buttons in the top-right corner of the carousel.

Data Sources

1. Built-in demo (no prop)

<AwesomeWaterWellGlassCarousel />

2. JavaScript array

<AwesomeWaterWellGlassCarousel data={myProductsArray} />

3. REST API endpoint

<AwesomeWaterWellGlassCarousel data="https://api.example.com/products" />

Expects the response to be a JSON array or an object with a data key containing an array.

4. Local JSON file

Place your file in the public/ folder of your Vite/CRA project:

<AwesomeWaterWellGlassCarousel data="/products.json" />

Interaction Reference

| Interaction | Behaviour | |------------------------------|--------------------------------------------------------------| | Hover over carousel | Pauses auto-rotation; shows ▶ Resume pill | | Mouse leave | Resumes auto-rotation | | Click active card / ↗ button | Fires onSlideClick(item, index) + item.onAction() | | Click non-active card | Snaps to that card (pauses auto-rotation) | | Drag left / right | Spins cylinder manually (pauses auto-rotation) | | ← Arrow key | Steps back one card (pauses auto-rotation) | | → Arrow key | Steps forward one card (pauses auto-rotation) | | Dot nav / orbit dots | Jumps to that slide (pauses auto-rotation) | | ▶ Resume pill click | Resumes auto-rotation from current position | | Theme dot click | Switches colour theme instantly (no rotation interruption) |

Advanced Usage

Controlled theme with external data + click handler

import { useState }              from "react";
import { AwesomeWaterWellGlassCarousel }  from "awesome-water-well-glass-carousel";
import "awesome-water-well-glass-carousel/style.css";

const PRODUCTS_URL = "https://api.myshop.com/watches";

export default function ShopPage() {
  const [selectedItem, setSelectedItem] = useState(null);

  return (
    <>
      <AwesomeWaterWellGlassCarousel
        data={PRODUCTS_URL}
        theme="blue"
        autoPlay={true}
        interval={4000}
        onSlideClick={(item, index) => {
          console.log(`Clicked: ${item.title} (index ${index})`);
          setSelectedItem(item);
        }}
      />

      {selectedItem && (
        <div className="product-detail">
          <h1>{selectedItem.title}</h1>
          <p>{selectedItem.price}</p>
        </div>
      )}
    </>
  );
}

Disable auto-rotation (manual only)

<AwesomeWaterWellGlassCarousel autoPlay={false} theme="yellow" />

Faster rotation

<AwesomeWaterWellGlassCarousel interval={1800} />

📄 License

📄 License

MIT