Snap Carousel
A native scroll-snap card carousel with arrow buttons and pager dots that stretch toward the active card.
$
View as Markdownnpx shadcn@latest add https://sundaeui.dev/r/snap-carousel.json'use client'
import { useRef, useState } from 'react'
import './snap-carousel.css'
export interface CarouselItem { id: string; title: string; body: string; tag?: string }
export interface SnapCarouselProps {
items: CarouselItem[]
cardWidth?: number
label?: string
fill?: 'dark' | 'light'
className?: string
}
/** Scroll-snap carousel with stretching dots. */
export function SnapCarousel({ items, cardWidth = 240, label = 'Highlights', fill = 'dark', className }: SnapCarouselProps) {
const track = useRef<HTMLDivElement>(null)
const [pos, setPos] = useState(0)
const step = cardWidth + 10
const max = items.length - 1
const go = (i: number) => track.current?.scrollTo({ left: Math.min(max, Math.max(0, i)) * step, behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth' })
const active = Math.round(pos)
const end = track.current ? track.current.scrollLeft + track.current.clientWidth >= track.current.scrollWidth - 4 : false
return (
<section className={['sd-scr', className].filter(Boolean).join(' ')} data-fill={fill} aria-roledescription="carousel" aria-label={label}>
<div ref={track} className="sd-scr__track" onScroll={(e) => setPos(e.currentTarget.scrollLeft / step)}>
{items.map((it, i) => (
<div key={it.id} className="sd-scr__card" role="group" aria-roledescription="slide" aria-label={`${i + 1} of ${items.length}`} style={{ width: cardWidth }}>
{it.tag && <span className="sd-scr__tag">{it.tag}</span>}
<div className="sd-scr__t">{it.title}</div>
<div className="sd-scr__b">{it.body}</div>
</div>
))}
</div>
<div className="sd-scr__bar">
<div className="sd-scr__dots">
{items.map((it, i) => {
const near = Math.max(0, 1 - Math.abs(pos - i))
return <button key={it.id} type="button" className="sd-scr__dot" aria-label={`Go to slide ${i + 1}`} aria-current={i === active} style={{ width: 6 + near * 16 }} onClick={() => go(i)} />
})}
</div>
<div className="sd-scr__arrs">
<button type="button" className="sd-scr__arr" aria-label="Previous slide" disabled={pos < 0.05} onClick={() => go(active - 1)}><svg viewBox="0 0 16 16" aria-hidden><path d="M10 3.5 5.5 8l4.5 4.5" /></svg></button>
<button type="button" className="sd-scr__arr" aria-label="Next slide" disabled={end} onClick={() => go(active + 1)}><svg viewBox="0 0 16 16" aria-hidden><path d="M6 3.5 10.5 8 6 12.5" /></svg></button>
</div>
</div>
</section>
)
}.sd-scr { --bg: #1c1c1c; --fg: #f6f6f6; --mute: #8e8e8e; --line: rgb(255 255 255 / 0.1); --soft: rgb(255 255 255 / 0.07); --strong: #fafafa; --on: #111;
color: var(--fg); font-size: 14px; line-height: 1.4; -webkit-tap-highlight-color: transparent; }
.sd-scr[data-fill='light'] { --bg: #fff; --fg: #121212; --mute: #6f6f6f; --line: rgb(0 0 0 / 0.09); --soft: rgb(0 0 0 / 0.05); --strong: #111; --on: #fff; }
.sd-scr button { font: inherit; color: inherit; background: none; border: 0; padding: 0; cursor: pointer; }
.sd-scr :focus-visible { outline: 2px solid var(--fg); outline-offset: 2px; }
.sd-scr .sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
.sd-scr { width: min(100%, 340px); }
.sd-scr__track { display: flex; gap: 10px; overflow-x: auto; scroll-snap-type: x mandatory; scroll-padding: 0 16px; padding: 4px 16px 8px; scrollbar-width: none; overscroll-behavior-x: contain; }
.sd-scr__track::-webkit-scrollbar { display: none; }
.sd-scr__card { flex: none; scroll-snap-align: start; height: 200px; padding: 16px; border-radius: 18px; background: var(--bg); box-shadow: inset 0 0 0 1px var(--line); display: flex; flex-direction: column; }
.sd-scr__tag { align-self: start; font-size: 11px; padding: 3px 8px; border-radius: 99px; background: var(--soft); color: var(--mute); }
.sd-scr__t { margin-top: auto; font-size: 17px; font-weight: 650; letter-spacing: -0.01em; }
.sd-scr__b { margin-top: 4px; font-size: 13px; color: var(--mute); }
.sd-scr__bar { display: flex; align-items: center; justify-content: space-between; padding: 8px 16px 0; }
.sd-scr__dots { display: flex; gap: 5px; align-items: center; }
.sd-scr__dot { height: 6px; border-radius: 99px; background: var(--mute); opacity: 0.4; transition: width 200ms, opacity 200ms; }
.sd-scr__dot[aria-current='true'] { opacity: 1; background: var(--fg); }
.sd-scr__arrs { display: flex; gap: 6px; }
.sd-scr__arr { display: grid; place-items: center; width: 34px; height: 34px; border-radius: 99px; box-shadow: inset 0 0 0 1px var(--line); transition: opacity 200ms, transform 140ms; }
.sd-scr__arr:active:not(:disabled) { transform: scale(0.9); }
.sd-scr__arr:disabled { opacity: 0.3; cursor: default; }
.sd-scr__arr svg { width: 14px; height: 14px; fill: none; stroke: currentColor; stroke-width: 1.7; stroke-linecap: round; stroke-linejoin: round; }
@media (prefers-reduced-motion: reduce) { .sd-scr *, .sd-scr *::before, .sd-scr *::after { animation: none !important; transition: none !important; } }Overview
Built on CSS scroll-snap, so swiping on touch and trackpads feels native and momentum works. The active dot stretches into a pill and tracks scroll position live.
Arrows scroll one card at a time and disable at the ends. Cards peek at the edge so people know there is more.
When to use
- Feature tours, testimonials, product cards on mobile.
When not to use
- Content everyone must see: carousels hide most of it.
Installation
$
pnpm dlx shadcn@latest add https://sundaeui.dev/r/snap-carousel.json$
npx shadcn@latest add https://sundaeui.dev/r/snap-carousel.json$
yarn dlx shadcn@latest add https://sundaeui.dev/r/snap-carousel.json$
bunx --bun shadcn@latest add https://sundaeui.dev/r/snap-carousel.jsonWorks in any React project. Files are written to components/sundae/. Read the source in the stage’s Code view.
- No dependencies beyond React 18 or later.
- Copy snap-carousel.tsx and snap-carousel.css into components/sundae/.
- The CSS file is imported by the component, so no extra configuration is needed.
- Import the component and use it as shown below.
Usage
import { SnapCarousel } from '@/components/sundae/snap-carousel'
<SnapCarousel />Props
| Prop | Type | Default |
|---|---|---|
items*Cards. | { id: string; title: string; body: string; tag?: string }[] | — |
cardWidthCard width in px. | number | 240 |
fillSurface: dark or light. | 'dark' | 'light' | 'dark' |
Accessibility
- A region with aria-roledescription="carousel"; each card is a group labelled "n of total".
- Dots are buttons that scroll to their card; arrows have names and disabled states.
- Reduced motion removes the movement and keeps every state change.
Customization
- Colours are CSS custom properties on .sd-scr; override them in your own stylesheet.
- fill="light" switches the built-in light palette.
FAQ
- Is Snap Carousel free?
- Yes. Snap Carousel is free for personal and commercial projects, with full source on this page.
- How do I install Snap Carousel?
- Run npx shadcn@latest add https://sundaeui.dev/r/snap-carousel.json. The files are written to components/sundae/. It has no dependencies beyond React 18 or later.
- Does Snap Carousel support keyboard and screen readers?
- A region with aria-roledescription="carousel"; each card is a group labelled "n of total". Dots are buttons that scroll to their card; arrows have names and disabled states.
- Does Snap Carousel respect reduced motion?
- Reduced motion removes the movement and keeps every state change.
More like this
All components →- Pro
Swipe Actions
Components · Refined Timezone Slider
Components · RefinedSlide to Confirm
Components · RefinedLightbox Gallery
Components · Refined- Pro
Glass Control Center
Components · Refined Toast Stack
Components · Refined