@pagix/carousel

A Puck-native carousel with two layouts:

• cards — multi-card peek showcase (3-4 cards visible, one centered, others peeking on the sides). Each card can carry its own image + title + subtitle. Small arrows + dot pagination.
• hero — single-image hero. One large image dominates, neighbours peek as thin slivers. Large circular arrows on the sides, no dots by default.

Carousel mechanics (active index, snap, loop, autoplay, keyboard) are shared; only the rendering per layout differs.

Install

pnpm add @pagix/carousel @anvilkit/ui @puckeditor/core

Styles

Import the package stylesheet once at the app entry:

import "@pagix/carousel/styles.css";

Quickstart

import "@pagix/carousel/styles.css";
import { Carousel, componentConfig, defaultProps } from "@pagix/carousel";

const config = {
	components: { Carousel: componentConfig },
};

const data = {
	root: { props: {} },
	content: [
		{
			props: {
				...defaultProps,
				layout: "cards",
				items: [
					{ image: "https://...", title: "Card 1", subtitle: "Subtitle" },
					{ image: "https://...", title: "Card 2", subtitle: "Subtitle" },
					{ image: "https://...", title: "Card 3", subtitle: "Subtitle" },
				],
			},
			type: "Carousel",
		},
	],
};

Props

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | layout | "cards" \| "hero" | "cards" | Visual layout. | | items | CarouselItem[] | [] | Slides. | | perView | number | 3 (cards) / 1 (hero) | How many items visible at once. | | aspect | "3:4" \| "16:9" \| "1:1" \| "4:3" | 3:4 (cards) / 16:9 (hero) | Item aspect ratio. | | showDots | boolean | true | Bottom dot pagination (auto-hidden in hero). | | showArrows | boolean | true | Prev/next navigation. | | arrowStyle | "small" \| "large" | small (cards) / large (hero) | Visual size of the arrow buttons. | | loop | boolean | true | Wrap around at the ends. | | autoplay | boolean | false | Auto-advance slides. | | autoplayInterval | number (ms) | 5000 | Autoplay step. | | gap | number (px) | 24 | Gap between items. | | background | BackgroundProps | white | Section background (image / video / color). | | classNames | Record<string, string> | — | Tailwind passthrough per style target. | | animation | AnimationProps | — | Entrance animation. |

CarouselItem

| Field | Type | Notes | | --- | --- | --- | | image | string | Background image (URL or data URL). | | title | string | Card title (used in cards layout). | | subtitle | string | Card subtitle. | | href | string | Optional clickable link. |

Edit mode

All interactive elements (arrows, dots, item links) are disabled in the Puck editor so authors don't trigger navigation while editing.