circular-carousel-react

A zero-dependency React circular card carousel with responsive mobile & desktop layouts. Built with TypeScript. Uses only inline CSS — no external styling libraries needed.

Installation

npm install circular-carousel-react

Peer dependencies: This library requires react >= 17.0.0 and react-dom >= 17.0.0.

Usage

import CircularCarousel from "circular-carousel-react";
import type { CardData } from "circular-carousel-react";

const cards: CardData[] = [
  {
    id: "1",
    image: "https://example.com/image.jpg",
    title: "Card Title",
    description: "A short description of the card.",
    link: "/some-link",
  },
  // ... more cards (recommended: 4–8)
];

function App() {
  return (
    <CircularCarousel
      cards={cards}
      heading="Featured"
      accentColor="#b80b0b"
      onCardClick={(card) => console.log(card)}
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | cards | CardData[] | [] | Required. Array of card data objects. | | heading | string | "" | Optional heading text displayed above the carousel. | | accentColor | string | "#b80b0b" | Accent colour for the CTA button. | | breakpoint | number | 768 | Pixel width threshold to switch between mobile and desktop layouts. | | onCardClick | (card: CardData) => void | — | Callback fired when the "Read more" button is clicked. |

CardData Interface

interface CardData {
  id: string;
  image: string;       // URL to the card image
  title: string;       // Card title text
  description: string; // Card description text
  link: string;        // URL or path (passed via onCardClick)
}

Features

• 🎡 Circular rotating wheel with smooth CSS transitions
• 📱 Responsive — automatically switches between mobile and desktop layouts
• 🎨 Customisable accent colour for CTA buttons
• ⏸️ Pause on hover (desktop) — auto-resumes when cursor leaves
• 🔧 Zero dependencies — only requires React as a peer dependency
• 📦 TypeScript-first — ships with full type declarations

Development

# Install dependencies
npm install

# Start the demo app
npm run dev

# Build the library
npm run build

License

MIT