{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "relay-carousel", "type": "registry:ui", "title": "Relay Carousel", "description": "A looping strip of photo cards where the first card leads: bigger, with its quote showing. Passing the lead on glides the strip, shrinks the old lead out of the way and grows the next card into its place, then sets the new quote in line by line.", "author": "KeyframeUI ", "categories": [ "carousel", "testimonials", "motion" ], "docs": "Live preview, examples and props: https://keyframeui.com/components/relay-carousel", "dependencies": [ "motion", "clsx", "tailwind-merge" ], "registryDependencies": [ "utils" ], "files": [ { "path": "components/ui/relay-carousel.tsx", "type": "registry:ui", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport {\n animate,\n AnimatePresence,\n motion,\n useMotionValue,\n useMotionValueEvent,\n useReducedMotion,\n useTransform,\n type AnimationPlaybackControls,\n type MotionStyle,\n type MotionValue,\n} from \"motion/react\";\n\nimport { cn } from \"@/lib/utils\";\n\n/**\n * Keep:\n * - Every card is placed and sized from one motion value, `place`, through CSS variables\n * (`--offset`, `--grow`, `--ahead`, `--drift`); the sizes live in CSS (`SIZES`), so the server\n * renders the strip already laid out.\n * - The leaving quote lifts off first, the strip glides on one spring, and the new quote sets in\n * line by line only once the strip is within `RELAY.settle` of its slot and nothing is dragging.\n * - A drag lands where the flick was heading and hands its speed to the glide as `velocity`, so a\n * release never snaps.\n * - The strip is endless: slots are virtualized around the lead, and only the copy nearest the\n * lead (`canonical`) is announced and focusable; repeats are `aria-hidden` and `inert`.\n * - Photo drift and zoom are CSS-only behind `motion-safe:`, so reduced motion turns them off\n * without a hydration mismatch; it also jumps the strip and holds autoplay until played.\n */\nconst TIMING = {\n /** The strip gliding to a new lead: a spring with no bounce, over `duration`. */\n glide: { type: \"spring\", bounce: 0 },\n /** How long the strip takes to glide to a new lead, in ms (the `duration` prop). */\n duration: 750,\n /** Between the lead's quote lines setting in, in ms (the `stagger` prop). */\n stagger: 80,\n /** The strip leaning toward a hovered arrow, and back. */\n lean: { type: \"spring\", visualDuration: 0.35, bounce: 0 },\n /** Release speed carried into where a drag lands, in seconds of travel. */\n flick: 0.2,\n /** How recently the pointer must have moved for a release to carry its speed, in ms. */\n fresh: 80,\n /** Without sideways wheel input before the strip snaps, in ms. */\n wheelIdle: 140,\n /** The autoplay ring filling over `autoPlay`, as an easing. */\n ring: \"linear\",\n /** The ring fading as autoplay pauses and plays, as a Tailwind class. */\n ringFade: \"duration-300\",\n /** A quote line, label or extra lifting off when its card stops leading, as Tailwind classes. */\n hide: \"duration-200 ease-out\",\n /** A quote line setting in from the blur once the strip lands, as Tailwind classes. */\n show: \"group-data-[shown=true]/relay:duration-700 group-data-[shown=true]/relay:ease-[cubic-bezier(0.16,1,0.3,1)]\",\n /** A resting card's photo brightening on hover, as a Tailwind class. */\n brighten: \"duration-500\",\n /** A round button's hover and press, as Tailwind classes. */\n button: \"duration-200 ease-out\",\n /** An arrow nudging on its button's hover, as Tailwind classes. */\n nudge: \"duration-200 ease-out\",\n /** The counter's digits rolling to the new lead. */\n count: { type: \"spring\", visualDuration: 0.4, bounce: 0 },\n} as const;\n\n/* ─────────────────────────────────────────────────────────\n * RELAY CAROUSEL STORYBOARD\n *\n * rest a strip of photo cards that runs off the right edge.\n * The first card is the lead: wider and taller than\n * the rest, its photo under a scrim, its quote set\n * above the name. The others show a name and a role.\n * Cards that already led fade into the left margin\n * relay next/prev, a click on a card, keys or autoplay pass\n * the lead on. The leaving quote lifts off first, then\n * the strip glides on one spring: the old lead shrinks\n * and slides out while the new one grows into its\n * place. Photos drift inside their cards as they\n * travel (14px a card) and the lead's eases back from\n * a 6% zoom. Once the strip has nearly landed, the new\n * quote sets in line by line from a soft blur\n * drag pull the strip with a finger or the mouse, or swipe\n * sideways on a trackpad. It snaps to the nearest\n * card, carrying the flick's speed\n * play with autoPlay, the ring around the pause button fills\n * as the timer. It holds while the pointer or keyboard\n * focus is inside, or the carousel is off screen\n * loop the strip never ends. Cards are virtualized and\n * repeated when there are too few to fill a wide screen\n * narrow the lead fills the width with the next card peeking,\n * and the controls move under the strip\n * reduced no glide, blur or autoplay: the lead switches at once\n * ───────────────────────────────────────────────────────── */\n\nconst RELAY = {\n settle: 0.3, // cards from rest at which the new quote starts to set in\n drag: 6, // px a press travels before it counts as a drag\n lean: 0.04, // cards the strip leans toward an arrow under the pointer\n} as const;\n\n// Card sizes live in CSS, so the server renders the strip already laid out. cqi is the carousel's width.\nconst SIZES = [\n \"[--relay-gap:0.75rem]\",\n \"[--relay-l:min(calc(100cqi_-_2_*_var(--relay-inset)_-_2.75rem),22rem)]\",\n \"[--relay-s:calc(var(--relay-l)_*_0.6)]\",\n \"[--relay-hs:calc(var(--relay-s)_*_1.3)]\",\n \"[--relay-hl:calc(var(--relay-l)_*_1.12)]\",\n \"@2xl:[--relay-gap:1rem]\",\n \"@2xl:[--relay-l:clamp(19rem,40cqi,25rem)]\",\n \"@2xl:[--relay-s:calc(var(--relay-l)_*_0.62)]\",\n \"@2xl:[--relay-hs:calc(var(--relay-s)_*_1.25)]\",\n \"@2xl:[--relay-hl:calc(var(--relay-hs)_*_1.2)]\",\n].join(\" \");\n\nconst INSET =\n \"[--relay-inset:max(1.25rem,calc((100cqi_-_76rem)_/_2))] @2xl:[--relay-inset:max(2.5rem,calc((100cqi_-_76rem)_/_2))]\";\n\nconst mod = (n: number, m: number) => ((n % m) + m) % m;\n\ntype Metrics = { width: number; inset: number; s: number; l: number; gap: number };\n\ntype Relay = {\n count: number;\n lead: number;\n revealed: number | null;\n /** ms between quote lines setting in. */\n stagger: number;\n /** px a photo drifts inside its card per card travelled. */\n drift: number;\n /** Where the strip is, in slots: the glide plus any lean toward a hovered arrow. */\n place: MotionValue;\n go: (slot: number) => void;\n onKeyDown: (event: React.KeyboardEvent) => void;\n};\n\ntype Slot = { slot: number; index: number; canonical: boolean };\n\nconst RelayContext = React.createContext(null);\nconst SlotContext = React.createContext({ slot: 0, index: 0, canonical: true });\n\nfunction useRelay() {\n const relay = React.useContext(RelayContext);\n if (!relay) throw new Error(\" must be rendered inside .\");\n return relay;\n}\n\nconst subscribeNothing = () => () => {};\n\n/* ── RelayCarousel ──────────────────────────────────────── */\n\nexport interface RelayCarouselProps extends Omit, \"onChange\"> {\n /** Shown top left, in line with the lead card. The controls sit opposite it. */\n heading?: React.ReactNode;\n /** The card that leads. Leave unset to let the carousel manage it. */\n index?: number;\n /** The card that leads first. */\n defaultIndex?: number;\n /** Called with the new lead's index, whatever moved it. */\n onIndexChange?: (index: number) => void;\n /** Passes the lead on every this many ms, with a pause button. Off for reduced motion until played. */\n autoPlay?: number;\n /** Left edge of the heading and the lead card, as a CSS length. `cqi` is the carousel's width. */\n inset?: string;\n /** Milliseconds the strip takes to glide to a new lead. */\n duration?: number;\n /** Milliseconds between the lead's quote lines setting in. */\n stagger?: number;\n /** How far each photo drifts inside its card per card the strip travels, in px. `0` keeps the photos still. */\n drift?: number;\n}\n\n/**\n * A looping strip of photo cards. The first card leads, larger, with its quote\n * showing; passing the lead on slides the strip and grows the next card into place.\n */\nexport function RelayCarousel({\n heading,\n index,\n defaultIndex = 0,\n onIndexChange,\n autoPlay,\n inset,\n duration = TIMING.duration,\n stagger = TIMING.stagger,\n drift = 14,\n className,\n children,\n onPointerEnter,\n onPointerLeave,\n onFocus,\n onBlur,\n ...props\n}: RelayCarouselProps) {\n const items = React.Children.toArray(children).filter(\n (child): child is React.ReactElement => React.isValidElement(child),\n );\n const count = items.length;\n const reduced = useReducedMotion() ?? false;\n const hydrated = React.useSyncExternalStore(subscribeNothing, () => true, () => false);\n const id = React.useId();\n const trackId = `${id}-track`;\n\n /* The lead is a slot on an endless strip; its item is the slot modulo the count. */\n const start = count ? mod(index ?? defaultIndex, count) : 0;\n const [lead, setLead] = React.useState({ slot: start, turn: 0 });\n const [step, setStep] = React.useState(1);\n const [announcement, setAnnouncement] = React.useState(\"\");\n const active = count ? mod(lead.slot, count) : -1;\n\n // A controlled index moves the lead the short way round.\n const [syncedIndex, setSyncedIndex] = React.useState(index);\n if (index !== syncedIndex) {\n setSyncedIndex(index);\n if (index !== undefined && count && mod(index, count) !== active) {\n let delta = mod(index - active, count);\n if (delta > count / 2) delta -= count;\n setLead({ slot: lead.slot + delta, turn: lead.turn + 1 });\n setStep(Math.sign(delta));\n }\n }\n\n const pos = useMotionValue(start);\n // Pointing at an arrow leans the strip a little that way, a hint of where it's about to go.\n const lean = useMotionValue(0);\n const place = useTransform(() => pos.get() + lean.get());\n const leanTo = (to: number) => {\n if (!reduced) animate(lean, to, TIMING.lean);\n };\n const glide = React.useRef(null);\n const release = React.useRef(0);\n const latest = React.useRef({ lead, count, items, onIndexChange });\n React.useLayoutEffect(() => {\n latest.current = { lead, count, items, onIndexChange };\n });\n\n const go = React.useCallback((slot: number, source: \"user\" | \"auto\" = \"user\") => {\n const { lead, count, items, onIndexChange } = latest.current;\n if (!count) return;\n const next = { slot, turn: lead.turn + 1 };\n latest.current.lead = next;\n setLead(next);\n if (slot !== lead.slot) setStep(Math.sign(slot - lead.slot));\n const index = mod(slot, count);\n if (source === \"user\") {\n const { name, role, quote } = items[index].props;\n setAnnouncement(\n `${index + 1} of ${count}. ${name}${typeof role === \"string\" ? `, ${role}` : \"\"}. “${quote}”`,\n );\n }\n if (slot !== lead.slot) onIndexChange?.(index);\n }, []);\n\n // Every new lead (or a snap back after a short drag) glides the strip to it.\n React.useEffect(() => {\n if (reduced) {\n pos.jump(lead.slot);\n return;\n }\n const controls = animate(pos, lead.slot, {\n ...TIMING.glide,\n visualDuration: duration / 1000,\n velocity: release.current,\n });\n release.current = 0;\n glide.current = controls;\n return () => controls.stop();\n }, [lead, reduced, pos, duration]);\n\n /* What the strip shows: the slots around the lead and wherever the strip is passing. */\n const [span, setSpan] = React.useState<[number, number]>([start, start]);\n const [revealed, setRevealed] = React.useState(start);\n const [dragging, setDragging] = React.useState(false);\n useMotionValueEvent(pos, \"change\", (value) => {\n const low = Math.floor(value);\n const high = Math.ceil(value);\n setSpan((prev) => (prev[0] === low && prev[1] === high ? prev : [low, high]));\n const slot = latest.current.lead.slot;\n setRevealed(Math.abs(value - slot) < RELAY.settle ? slot : null);\n });\n\n const trackRef = React.useRef(null);\n const probeRef = React.useRef(null);\n const [metrics, setMetrics] = React.useState(null);\n React.useLayoutEffect(() => {\n const track = trackRef.current;\n const probe = probeRef.current;\n if (!track || !probe) return;\n const [inset, s, l, gap] = Array.from(probe.children) as HTMLElement[];\n const observer = new ResizeObserver(() => {\n const next = {\n width: track.clientWidth,\n inset: inset.offsetWidth,\n s: s.offsetWidth,\n l: l.offsetWidth,\n gap: gap.offsetWidth,\n };\n setMetrics((prev) =>\n prev &&\n prev.width === next.width &&\n prev.inset === next.inset &&\n prev.s === next.s &&\n prev.l === next.l &&\n prev.gap === next.gap\n ? prev\n : next,\n );\n });\n observer.observe(track);\n for (const el of [inset, s, l, gap]) observer.observe(el);\n return () => observer.disconnect();\n }, []);\n\n const pitch = metrics ? metrics.s + metrics.gap : 1;\n const before = metrics ? Math.ceil(metrics.inset / pitch) + 1 : 2;\n const after = metrics ? Math.ceil((metrics.width - metrics.inset - metrics.l) / pitch) + 1 : 0;\n const low = Math.min(span[0], lead.slot) - before;\n const high = Math.max(Math.max(span[1], lead.slot) + after, low + count - 1);\n const slots: Slot[] = [];\n if (count === 1) slots.push({ slot: lead.slot, index: 0, canonical: true });\n else if (count) {\n // Each item is announced once: the copy nearest the lead. Repeats are decoration.\n const nearest = new Map();\n for (let slot = low; slot <= high; slot++) {\n const i = mod(slot, count);\n const best = nearest.get(i);\n if (best === undefined || Math.abs(slot - lead.slot) <= Math.abs(best - lead.slot)) {\n nearest.set(i, slot);\n }\n }\n for (let slot = low; slot <= high; slot++) {\n const i = mod(slot, count);\n slots.push({ slot, index: i, canonical: nearest.get(i) === slot });\n }\n }\n\n /* Autoplay: the ring fills while nothing holds it, then the lead moves on. */\n const progress = useMotionValue(0);\n const [paused, setPaused] = React.useState(null);\n const [hovered, setHovered] = React.useState(false);\n const [focused, setFocused] = React.useState(false);\n const [seen, setSeen] = React.useState(true);\n const canPlay = !!autoPlay && autoPlay > 0 && count > 1;\n const playing = canPlay && !(paused ?? (hydrated && reduced));\n const held = hovered || focused || dragging || !seen;\n\n React.useLayoutEffect(() => {\n progress.jump(0);\n }, [lead.slot, progress]);\n\n React.useEffect(() => {\n if (!playing || held) return;\n const controls = animate(progress, 1, {\n duration: ((autoPlay ?? 0) / 1000) * (1 - progress.get()),\n ease: TIMING.ring,\n onComplete: () => go(latest.current.lead.slot + 1, \"auto\"),\n });\n return () => controls.stop();\n }, [playing, held, lead.slot, autoPlay, progress, go]);\n\n React.useEffect(() => {\n const track = trackRef.current;\n if (!canPlay || !track) return;\n let inView = true;\n const update = () => setSeen(inView && document.visibilityState === \"visible\");\n const observer = new IntersectionObserver(\n ([entry]) => {\n inView = entry.isIntersecting;\n update();\n },\n { threshold: 0.25 },\n );\n observer.observe(track);\n document.addEventListener(\"visibilitychange\", update);\n return () => {\n observer.disconnect();\n document.removeEventListener(\"visibilitychange\", update);\n };\n }, [canPlay]);\n\n /* Dragging: the strip follows the pointer, then lands where the flick was heading. */\n const pointer = React.useRef({\n id: -1,\n x: 0,\n from: 0,\n moved: false,\n swallow: false,\n samples: [] as { x: number; t: number }[],\n });\n\n const unit = () => {\n const m = metrics;\n return m ? (m.s + m.l) / 2 + m.gap : 300;\n };\n\n const onPointerDown = (event: React.PointerEvent) => {\n const p = pointer.current;\n p.swallow = false;\n if (count < 2 || event.button !== 0) return;\n if ((event.target as HTMLElement).closest(\"a, input, textarea, select, [data-relay-extra]\")) return;\n p.id = event.pointerId;\n p.x = event.clientX;\n p.from = pos.get();\n p.moved = false;\n p.samples = [{ x: event.clientX, t: event.timeStamp }];\n };\n\n const onPointerMove = (event: React.PointerEvent) => {\n const p = pointer.current;\n if (event.pointerId !== p.id) return;\n const dx = event.clientX - p.x;\n if (!p.moved) {\n if (Math.abs(dx) < RELAY.drag) return;\n p.moved = true;\n glide.current?.stop();\n p.from = pos.get() + dx / unit();\n event.currentTarget.setPointerCapture(event.pointerId);\n setDragging(true);\n }\n pos.set(p.from - dx / unit());\n p.samples.push({ x: event.clientX, t: event.timeStamp });\n if (p.samples.length > 6) p.samples.shift();\n };\n\n const endDrag = (event: React.PointerEvent) => {\n const p = pointer.current;\n if (event.pointerId !== p.id) return;\n p.id = -1;\n if (!p.moved) return;\n p.swallow = true;\n setDragging(false);\n const first = p.samples[0];\n const last = p.samples[p.samples.length - 1];\n const elapsed = last.t - first.t;\n const speed = elapsed > 0 && event.timeStamp - last.t < TIMING.fresh ? (last.x - first.x) / elapsed : 0; // px/ms\n const cards = -(speed * 1000) / unit(); // cards/s, positive toward the next card\n const reach = Math.max(1, Math.ceil((metrics?.width ?? 1000) / pitch) - 1);\n const landing = Math.round(pos.get() + cards * TIMING.flick);\n const slot = Math.max(Math.round(p.from) - reach, Math.min(Math.round(p.from) + reach, landing));\n release.current = reduced ? 0 : cards;\n go(slot);\n };\n\n /* Sideways trackpad swipes scrub the strip and snap once they stop. */\n React.useEffect(() => {\n const track = trackRef.current;\n if (!track || count < 2) return;\n let timer = 0;\n const onWheel = (event: WheelEvent) => {\n if (Math.abs(event.deltaX) <= Math.abs(event.deltaY)) return;\n event.preventDefault();\n glide.current?.stop();\n setDragging(true);\n const m = metrics;\n const size = m ? (m.s + m.l) / 2 + m.gap : 300;\n pos.set(pos.get() + event.deltaX / size);\n window.clearTimeout(timer);\n timer = window.setTimeout(() => {\n setDragging(false);\n go(Math.round(pos.get()));\n }, TIMING.wheelIdle);\n };\n track.addEventListener(\"wheel\", onWheel, { passive: false });\n return () => {\n track.removeEventListener(\"wheel\", onWheel);\n window.clearTimeout(timer);\n };\n }, [count, metrics, pos, go]);\n\n /* Keys: ←/→ pass the lead, Home/End go the short way to the first and last card. Focus follows the lead. */\n const keyboard = React.useRef(false);\n const onKeyDown = (event: React.KeyboardEvent) => {\n const slot = latest.current.lead.slot;\n const toIndex = (i: number) => {\n let delta = mod(i - slot, count);\n if (delta > count / 2) delta -= count;\n return slot + delta;\n };\n let to: number | null = null;\n if (event.key === \"ArrowRight\") to = slot + 1;\n else if (event.key === \"ArrowLeft\") to = slot - 1;\n else if (event.key === \"Home\") to = toIndex(0);\n else if (event.key === \"End\") to = toIndex(count - 1);\n if (to === null) return;\n event.preventDefault();\n keyboard.current = true;\n go(to);\n };\n React.useEffect(() => {\n if (!keyboard.current) return;\n keyboard.current = false;\n trackRef.current?.querySelector(`[data-relay-slot=\"${lead.slot}\"]`)?.focus();\n }, [lead]);\n\n return (\n \n {\n if (event.pointerType === \"mouse\") setHovered(true);\n onPointerEnter?.(event);\n }}\n onPointerLeave={(event) => {\n setHovered(false);\n onPointerLeave?.(event);\n }}\n onFocus={(event) => {\n if (event.target.matches(\":focus-visible\")) setFocused(true);\n onFocus?.(event);\n }}\n onBlur={(event) => {\n if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setFocused(false);\n onBlur?.(event);\n }}\n >\n \n {heading != null && (\n
\n {heading}\n
\n )}\n\n \n \n go(lead.slot - 1)}\n onHover={(on) => leanTo(on ? -RELAY.lean : 0)}\n >\n \n \n go(lead.slot + 1)}\n onHover={(on) => leanTo(on ? RELAY.lean : 0)}\n >\n \n \n {canPlay && (\n setPaused(playing)}\n >\n \n \n \n {playing ? : }\n \n )}\n \n\n