@designdaddy/carousel

Version 0.0.1 — first public release.

Image carousel for full-width heroes — autoplay, Ken Burns zoom, fade or slide, animated captions, arrows, and pagination. Extra layouts (banner, framed, overlay, editorial) and motion (zoom, flip) stay available.

Peer dependency: React 17+ (18 / 19 supported).

Table of contents

1. Install
2. Quick start
3. Create React App
4. Slides (images)
5. Four styles
6. Animations
7. Four indicator styles
8. Previous / next buttons
9. Height, font, theme
10. Carousel props
11. Feature toggles
12. Responsive
13. Styling
14. Compose yourself
15. Exports
16. Local pack
17. Publish to npm

Install

npm install @designdaddy/carousel

Import the component and the CSS (required — styles do not inject from the JS bundle):

import { Carousel } from "@designdaddy/carousel";
import "@designdaddy/carousel/styles.css";

Quick start

Pass your own image URLs. The package ships no sample photos.

import { Carousel } from "@designdaddy/carousel";
import "@designdaddy/carousel/styles.css";

const slides = [
  {
    src: "/slides/press-1.jpg",
    alt: "Offset press",
    caption: "A top Digital and Multicolour offset printing company in India.",
  },
  {
    src: "/slides/press-2.jpg",
    alt: "Bindery",
    caption: "Finishing, binding, and dispatch under one roof.",
  },
];

export default function App() {
  return (
    <Carousel
      slides={slides}
      variant="hero"
      animation="fade"
      autoplay
      kenBurns
      interval={7000}
    />
  );
}

Create React App

Do not install with "file:.../packages/carousel" (npm makes a junction → two copies of React → blank page).

From this package folder:

cd packages/carousel
npm run build
npm pack

In the CRA app:

npm install C:/Users/AarthiDatapro/Documents/Projects/Live/Web/designdaddy/packages/carousel/designdaddy-carousel-0.0.1.tgz

App.js:

import { Carousel } from "@designdaddy/carousel";
import "@designdaddy/carousel/styles.css";

After publish, switch the app to:

npm install @designdaddy/carousel

Slides (images)

slides (alias: items) is an array. Each item can be a URL string or an object:

| Field | Meaning | |-------|---------| | src | Image URL (required) | | alt | Alt text | | caption | Line under / over the image | | title | Optional heading (overlay / editorial) | | href | Optional link wrapping the image | | srcSet / sizes | Responsive image hints | | fit | cover (default) or contain for this slide |

<Carousel
  slides={[
    "https://cdn.example.com/one.jpg",
    { src: "/two.jpg", alt: "Hall 2", caption: "Plant walkthrough", fit: "contain" },
  ]}
  objectFit="cover"
/>

objectFit sets the default for every slide (cover or contain). Per-slide fit wins.

Four styles

variant changes layout, arrows, caption, and chrome. Mix freely with animation + indicator.

| variant | Look | |-----------|------| | hero | Full-width responsive hero — autoplay + Ken Burns + fade by default | | banner | Same chrome as hero, without the hero defaults | | framed | Rounded card + shadow, caption and indicators below the photo, square-ish arrows | | overlay | Dark gradient, large title on the image, ghost outline arrows | | editorial | White inset frame, serif strip caption, large line arrows |

<Carousel slides={slides} variant="hero" animation="fade" autoplay kenBurns />
<Carousel slides={slides} variant="banner" />
<Carousel slides={slides} variant="framed" />
<Carousel slides={slides} variant="overlay" />
<Carousel slides={slides} variant="editorial" />

Animations

animation is how the next image arrives:

| animation | Motion | |-------------|--------| | slide | Horizontal track (default) | | fade | Cross-fade | | zoom | Scale in | | flip | 3D flip |

<Carousel slides={slides} animation="fade" />

Swipe left / right on touch, and ← → when the carousel is focused.

Four indicator styles

indicator is the page-control look (independent of variant):

| indicator | Look | |-------------|------| | dots | Circles | | bars | Short lines that grow when active | | pills | Capsules | | numbers | 01 02 03 with an underline on the active slide |

<Carousel slides={slides} indicator="bars" />

Previous / next buttons

Shown by default. Hide with showArrows={false}. Replace the chevron with any node:

<Carousel
  slides={slides}
  prevLabel="Previous"
  nextLabel="Next"
  prevIcon={<span>‹</span>}
  nextIcon={<span>›</span>}
  theme={{
    arrowBg: "#1e88e5",
    arrowColor: "#fff",
    arrowSize: "2.75rem",
    arrowRadius: "999px",
  }}
/>

Height, font, theme

Height is a CSS size (28rem, 420px, or a number treated as px):

<Carousel slides={slides} height="420px" />
<Carousel slides={slides} height={360} />
<Carousel slides={slides} theme={{ height: "32rem" }} />

Font family and sizes:

<Carousel
  slides={slides}
  theme={{
    fontFamily: "Georgia, serif",
    fontSize: "16px",
    captionSize: "1rem",
    titleSize: "1.75rem",
    captionWeight: 600,
    primary: "#1e88e5",
    captionBg: "#1e88e5",
    captionColor: "#fff",
  }}
/>

Or raw variables:

<Carousel className="hero-carousel" style={{ "--crs-height": "24rem" }} slides={slides} />

.hero-carousel { --crs-primary: #0f766e; }
.hero-carousel .crs-caption__text { letter-spacing: 0.02em; }

Carousel props

| Prop | Default | Meaning | |------|---------|---------| | slides / items | [] | Images + captions | | index | — | Controlled slide index | | defaultIndex | 0 | Uncontrolled start | | onIndexChange | — | (index) => void | | variant | "hero" | hero | banner | framed | overlay | editorial | | animation | "fade" on hero, "slide" otherwise | fade | slide | zoom | flip | | indicator | "dots" | dots | bars | numbers | pills | | height | "min(72vh, 42rem)" on hero | Viewport height | | objectFit | "cover" | Default object-fit | | loop | true | Wrap around at the ends | | autoplay | true on hero | Advance on a timer | | interval | 7000 | Autplay ms (matches Ken Burns) | | pauseOnHover | true | Pause autoplay and Ken Burns | | kenBurns | true on hero | Slow zoom/pan on the active image | | animateCaption | true | Caption slides up on each change | | prevLabel / nextLabel | — | Button accessible names | | prevIcon / nextIcon | chevron | Custom button content | | className / style / theme | — | Styling hooks |

Feature toggles

undefined → on. false hides the piece.

| Prop | Default | |------|---------| | showArrows | true | | showIndicators | true | | showCaption | true | | kenBurns | true on hero | | autoplay | true on hero |

Responsive

Layout uses container queries on .crs-root (not the window), so the carousel compresses inside a narrow column the same way it does on a phone:

• arrows shrink and sit closer to the edges
• caption wraps and uses a smaller type size
• swipe still changes slides

Set height yourself for short mobile heroes (height="16rem").

Styling

Three layers, same idea as navbar:

1. theme={{…}} → --crs-* on .crs-root
2. className + your CSS (import after the package CSS)
3. style inline / extra variables

Friendly theme keys: primary, arrowBg, arrowColor, arrowSize, arrowRadius, captionBg, captionColor, captionSize, titleSize, fontFamily, fontSize, height, radius, shadow, indicator, indicatorActive, duration, imageFit.

Class names:

| Class | Role | |-------|------| | .crs-root | Root + tokens | | .crs-root--banner / --framed / --overlay / --editorial | Style | | .crs-root--anim-slide / --fade / --zoom / --flip | Animation | | .crs-viewport / .crs-track / .crs-slide | Stage | | .crs-arrow / --prev / --next | Buttons | | .crs-caption / __title / __text | Copy | | .crs-indicators / --dots / --bars / --numbers / --pills | Pager |

Compose yourself

import {
  CarouselShell,
  CarouselSlide,
  CarouselArrows,
  CarouselCaption,
  CarouselIndicators,
} from "@designdaddy/carousel";

Most apps only need Carousel.

Exports

import {
  Carousel,
  CarouselShell,
  CarouselSlide,
  CarouselArrows,
  CarouselCaption,
  CarouselIndicators,
  VARIANTS,
  ANIMATIONS,
  INDICATORS,
  THEME_KEYS,
  themeToCssVars,
  resolveFeature,
} from "@designdaddy/carousel";

Local pack

cd packages/carousel
npm run build
npm pack

Then in a host app:

npm install /path/to/designdaddy-carousel-0.0.1.tgz

Publish to npm

cd packages/carousel
npm run build
npm publish --access public

Folder layout

packages/carousel/
  package.json
  README.md
  src/
    index.js
    Carousel/
    CarouselShell/
    CarouselSlide/
    CarouselArrows/
    CarouselCaption/
    CarouselIndicators/
    styles/carousel.css
    utils/

Notes for packaging

1. "exports" points at dist/ — npm run build runs before publish.
2. CSS is dist/styles.css, imported as @designdaddy/carousel/styles.css.
3. react / react-dom are peerDependencies.
4. Consumers pass slides — no sample images in the package.