carousel cards.md
Momentum Rail
A card rail you flick with momentum, snapping on a spring, with scroll-driven cover-flow depth and parallax.
Source: https://kokonutui.com/docs/cards/carousel-cards
Installation
npx shadcn@latest add @kokonutui/carousel-cards
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items? |
RailItem[] |
built-in |
|
title? |
string |
"Weekend escapes" |
|
eyebrow? |
string |
"Picked for this autumn" |
|
defaultFavorites? |
string[] |
[] |
Ids saved on first render. |
onToggleFavorite? |
ToggleFavorite |
Called when a card's heart is toggled, with the item id and new state. | |
onSelect? |
(item: RailItem) => void |
Called when a card without an href is clicked or activated. |
|
className? |
string |
Extra classes for the root element. |
RailItem
| Field | Type | Description |
|---|---|---|
id |
string |
|
title |
string |
|
location |
string |
|
image? |
string |
Photo URL, rendered with a plain . Falls back to scene. |
imageAlt? |
string |
Alt text for image. Empty by default: the title already names it. |
scene? |
RailScene |
Built-in drawn artwork, used when there is no image. |
badge? |
string |
|
dates? |
string |
|
price |
number |
|
currency? |
string |
|
priceLabel? |
string |
|
rating? |
number |
|
reviewCount? |
number |
|
href? |
string |
ToggleFavorite
type ToggleFavorite = (id: string, favorite: boolean) => void;
RailScene
type RailScene = | "city" | "mountains" | "dunes" | "lake" | "islands" | "skyline" | "terraces" | "coast";
Source
"use client";
/**
* @author: @dorianbaffier
* @description: Momentum Rail. A card rail you can flick with the mouse: the
* release velocity projects an end point, a spring snaps to the nearest card
* and the ends rubber-band. Scroll position drives a cover-flow depth, image
* parallax and the centered card's details with CSS scroll-driven animations.
* @version: 2.0.0
* @date: 2026-10-14
* @license: MIT
* @website: https://kokonutui.com
* @github: https://github.com/kokonut-labs/kokonutui
*/
import { ChevronLeft, ChevronRight, Star } from "lucide-react";
import { type CSSProperties, type ReactNode, type RefObject, useCallback, useEffect, useRef, useState } from "react";
import { cn } from "@/lib/utils";
export type RailScene =
| "city"
| "mountains"
| "dunes"
| "lake"
| "islands"
| "skyline"
| "terraces"
| "coast";
export interface RailItem {
id: string;
title: string;
location: string;
/** Photo URL, rendered with a plain <img>. Falls back to `scene`. */
image?: string;
/** Alt text for `image`. Empty by default: the title already names it. */
imageAlt?: string;
/** Built-in drawn artwork, used when there is no `image`. */
scene?: RailScene;
badge?: string;
dates?: string;
price: number;
currency?: string;
priceLabel?: string;
rating?: number;
reviewCount?: number;
href?: string;
}
export type ToggleFavorite = (id: string, favorite: boolean) => void;
export interface CarouselCardsProps {
items?: RailItem[];
title?: string;
eyebrow?: string;
/** Ids saved on first render. */
defaultFavorites?: string[];
/** Called when a card's heart is toggled, with the item id and new state. */
onToggleFavorite?: ToggleFavorite;
/** Called when a card without an `href` is clicked or activated. */
onSelect?: (item: RailItem) => void;
className?: string;
}
const DEFAULT_ITEMS: RailItem[] = [
{
id: "lisbon",
title: "Weekend in Lisbon",
location: "Lisbon, Portugal",
scene: "city",
badge: "2 nights",
dates: "Oct 24 – 26",
price: 340,
rating: 4.92,
reviewCount: 318,
},
{
id: "dolomites",
title: "Slow days in the Dolomites",
location: "Val Gardena, Italy",
scene: "mountains",
badge: "4 nights",
dates: "Nov 3 – 7",
price: 610,
rating: 4.97,
reviewCount: 142,
},
{
id: "dunes",
title: "Two nights in the dunes",
location: "Merzouga, Morocco",
scene: "dunes",
badge: "2 nights",
dates: "Nov 14 – 16",
price: 280,
rating: 4.88,
reviewCount: 96,
},
{
id: "lapland",
title: "Lake cabin under the aurora",
location: "Inari, Finland",
scene: "lake",
badge: "3 nights",
dates: "Dec 5 – 8",
price: 520,
rating: 4.95,
reviewCount: 210,
},
{
id: "naxos",
title: "Island hopping by ferry",
location: "Naxos, Greece",
scene: "islands",
badge: "5 nights",
dates: "May 9 – 14",
price: 740,
rating: 4.9,
reviewCount: 187,
},
{
id: "tokyo",
title: "Late trains and night markets",
location: "Tokyo, Japan",
scene: "skyline",
badge: "4 nights",
dates: "Mar 20 – 24",
price: 890,
rating: 4.96,
reviewCount: 402,
},
{
id: "ubud",
title: "Rice terraces at dawn",
location: "Ubud, Indonesia",
scene: "terraces",
badge: "3 nights",
dates: "Jan 12 – 15",
price: 390,
rating: 4.91,
reviewCount: 133,
},
{
id: "coast-road",
title: "Coast road, windows down",
location: "Big Sur, United States",
scene: "coast",
badge: "3 nights",
dates: "Apr 2 – 5",
price: 560,
rating: 4.89,
reviewCount: 158,
},
];
const RAIL_CSS = `
@keyframes kokonutui-rail-tilt {
0% { transform: perspective(900px) translateZ(-180px) rotateY(-14deg); }
50% { transform: perspective(900px) translateZ(0) rotateY(0deg); }
100% { transform: perspective(900px) translateZ(-180px) rotateY(14deg); }
}
@keyframes kokonutui-rail-parallax {
from { transform: translate3d(calc(var(--rail-depth) * -1), 0, 0); }
to { transform: translate3d(var(--rail-depth), 0, 0); }
}
@keyframes kokonutui-rail-details {
0%, 32% { opacity: 0; transform: translate3d(0, 6px, 0); }
45%, 55% { opacity: 1; transform: translate3d(0, 0, 0); }
68%, 100% { opacity: 0; transform: translate3d(0, 6px, 0); }
}
@supports (animation-timeline: view()) {
.kokonutui-rail-card { view-timeline: --kokonutui-rail inline; }
.kokonutui-rail-details {
animation: kokonutui-rail-details linear both;
animation-timeline: --kokonutui-rail;
}
@media (prefers-reduced-motion: no-preference) {
.kokonutui-rail-tilt {
animation: kokonutui-rail-tilt linear both;
animation-timeline: --kokonutui-rail;
}
.kokonutui-rail-layer {
animation: kokonutui-rail-parallax linear both;
animation-timeline: --kokonutui-rail;
}
}
}
`;
const TONE = {
sun: "fill-white dark:fill-zinc-400",
far: "fill-zinc-300 dark:fill-zinc-800",
mid: "fill-zinc-400 dark:fill-zinc-900",
near: "fill-zinc-600 dark:fill-zinc-950",
sky: "fill-zinc-200 dark:fill-zinc-700",
} as const;
const Scene = ({ scene }: { scene: RailScene }) => (
<div
aria-hidden="true"
className="absolute inset-0 bg-zinc-200 dark:bg-zinc-700"
>
{SCENES[scene].map((layer) => (
<div
className={LAYER_CLASS}
key={layer.depth}
style={{ "--rail-depth": `${layer.depth}%` } as CSSProperties}
>
<svg
aria-hidden="true"
className="h-full w-full"
preserveAspectRatio="xMidYMax slice"
viewBox="0 0 208 200"
>
{layer.content}
</svg>
</div>
))}
</div>
);
const RailCard = ({ item, saved, onToggleSaved, onSelect }: { item: RailItem; saved: boolean; onToggleSaved: (id: string) => void; onSelect?: (item: RailItem) => void; }) => (
<li className="kokonutui-rail-card w-(--rail-card) flex-none snap-center">
<div className="kokonutui-rail-tilt group/rail-card relative">
<div className="relative aspect-[4/5] overflow-hidden rounded-2xl bg-zinc-200 ring-zinc-900 ring-offset-2 ring-offset-white group-has-[[data-rail-link]:focus-visible]/rail-card:ring-2 dark:bg-zinc-800 dark:ring-zinc-100 dark:ring-offset-zinc-950">
{item.image ? (
<div className={cn(LAYER_CLASS, "[--rail-depth:8%]")}>
<img
alt={item.imageAlt ?? ""}
className="h-full w-full object-cover"
decoding="async"
draggable={false}
height={500}
loading="lazy"
src={item.image}
width={520}
/>
</div>
) : (
<Scene scene={item.scene ?? "mountains"} />
)}
{item.badge && (
<span className="absolute top-3 left-3 rounded-md bg-white px-1.5 py-0.5 font-medium text-[11px] text-zinc-900 shadow-sm dark:bg-zinc-950 dark:text-zinc-100">
{item.badge}
</span>
)}
<FavoriteButton label={item.title} onToggle={() => onToggleSaved(item.id)} saved={saved} />
</div>
<div className="px-0.5 pt-3">
<h3 className="truncate font-medium text-sm text-zinc-900 tracking-tight dark:text-zinc-100">
{item.href ? (
<a
className={STRETCHED}
data-rail-link=""
draggable={false}
href={item.href}
>
{item.title}
</a>
) : (
<button
className={cn(STRETCHED, "cursor-pointer text-left")}
data-rail-link=""
onClick={() => onSelect?.(item)}
type="button"
>
{item.title}
</button>
)}
</h3>
<p className="truncate text-xs text-zinc-500 dark:text-zinc-400">
{item.location}
</p>
<CardDetails item={item} />
</div>
</div>
</li>
);
export default function CarouselCards({ items = DEFAULT_ITEMS, title = "Weekend escapes", eyebrow = "Picked for this autumn", defaultFavorites = [], onToggleFavorite, onSelect, className, }: CarouselCardsProps) {
const scrollerRef = useRef<HTMLElement>(null);
const trackRef = useRef<HTMLUListElement>(null);
const [active, setActive] = useState(0);
const [saved, setSaved] = useState<ReadonlySet<string>>(() => new Set(defaultFavorites));
const { goTo, currentIndex } = useMomentumRail(scrollerRef, trackRef, setActive);
const toggleSaved = (id: string) => {
const next = !saved.has(id);
setSaved((prev) => {
const copy = new Set(prev);
if (next) {
copy.add(id);
} else {
copy.delete(id);
}
return copy;
});
onToggleFavorite?.(id, next);
};
const step = (delta: number) => goTo(currentIndex() + delta);
return (
<section
aria-label={title}
aria-roledescription="carousel"
className={cn("@container/rail w-full py-4 @3xl/rail:[--rail-card:16rem] @md/rail:[--rail-card:15rem] [--rail-card:13.5rem]", className)}
>
<div className="mb-2 flex items-end justify-between gap-4 px-4">
<div className="min-w-0">
<p className="text-xs text-zinc-500 dark:text-zinc-400">{eyebrow}</p>
<h2 className="truncate font-semibold text-lg text-zinc-900 tracking-tight dark:text-zinc-100">
{title}
</h2>
</div>
<div className="flex shrink-0 items-center gap-2">
<span
aria-live="polite"
className="mr-1 text-xs text-zinc-500 tabular-nums dark:text-zinc-400"
>
<span className="sr-only">Card </span>
{String(active + 1).padStart(2, "0")}
<span aria-hidden="true"> / </span>
<span className="sr-only"> of </span>
{String(items.length).padStart(2, "0")}
</span>
<button
aria-disabled={active === 0}
aria-label="Previous"
className={ARROW_CLASS}
onClick={() => step(-1)}
type="button"
>
<ChevronLeft aria-hidden="true" className="size-4" />
</button>
<button
aria-disabled={active === items.length - 1}
aria-label="Next"
className={ARROW_CLASS}
onClick={() => step(1)}
type="button"
>
<ChevronRight aria-hidden="true" className="size-4" />
</button>
</div>
</div>
<section
aria-label={`${title}, use arrow keys to move`}
className="relative snap-x snap-mandatory overflow-x-auto overscroll-x-contain py-6 outline-none [scrollbar-width:none] focus-visible:ring-2 focus-visible:ring-zinc-900 focus-visible:ring-inset data-[dragging=true]:cursor-grabbing data-[free=true]:snap-none dark:focus-visible:ring-zinc-100 [&::-webkit-scrollbar]:hidden [@media(pointer:fine)]:cursor-grab [@media(pointer:fine)]:select-none"
ref={scrollerRef}
tabIndex={0}
>
<ul
className="relative flex w-max gap-4 px-[calc(50cqw-var(--rail-card)/2)]"
ref={trackRef}
>
{items.map((item) => (
<RailCard
item={item}
key={item.id}
onSelect={onSelect}
onToggleSaved={toggleSaved}
saved={saved.has(item.id)}
/>
))}
</ul>
</section>
<style href="kokonutui-carousel-cards" precedence="default">
{RAIL_CSS}
</style>
</section>
);
}