Skip to content

Slideshow

Endless carousel that auto-plays, can be dragged and peeks at the next slide.

$npx shadcn@latest add https://framebrick.co/r/slideshow.json

From the Nitip template, see it in context.

Fishing boats reflected in a still harbourHarbour

Examples

No loop

A row with two ends: the arrow at an end fades and is disabled, and a drag past it springs back.

Fishing boats reflected in a still harbourHarbour
Ears of wheat against a pale skyField notes
<Slideshow items={stories} getKey={(s) => s.slug} label="Member stories" loop={false} interval={0} arrows="above" perView={{ base: 1, sm: 2 }} renderItem={(s) => <StoryCard story={s} />} />

Arrows above

Two small arrows in a row above the slides, at the right, always shown; two slides in view.

Inspiration

Fishing boats reflected in a still harbourHarbour
Ears of wheat against a pale skyField notes
<Slideshow items={posts} getKey={(p) => p.slug} label="Inspiration" gap={10} arrows="above" drag={false} perView={{ base: 1, sm: 2 }} renderItem={(p) => <PostCard post={p} />} />

Side arrows

One round arrow on each side, shown while the pointer is over the photo or an arrow has the focus; the dots sit over the foot of it.

Glass-walled corridor with a sofa and a floor lamp
<Slideshow items={homes} getKey={(h) => h.slug} label="Featured homes" gap={0} arrows="sides" dots="inside" slideClassName="w-full" renderItem={(h) => <HomePhoto home={h} />} />

Card photos

A listing card whose photo turns through three pictures while the card is pointed at, then goes back to the first at once.

<a href="/homes/almond-street" className="group block">
  <Slideshow items={photos} getKey={(p) => p.src} label="Photos of 14 Almond Street" gap={0} arrows="none" dots="inside" run="hover" hoverTarget=".group" interval={1500} slideClassName="w-full" renderItem={(p) => <Photo photo={p} />} />
  <span>14 Almond Street</span>
</a>

Row

Small cards, two at a time and more as it widens, that cannot be dragged; every card in view can be read and tabbed to.

<Slideshow
  items={posts}
  getKey={(p) => p.slug}
  label="Latest posts"
  gap={30}
  arrows="none"
  drag={false}
  perView={{ base: 1, sm: 2, lg: 4 }}
  renderItem={(p) => <PostCard post={p} />}
/>

Dots

A row of dots under the frame, one per slide; a dot goes to its slide the shorter way round the loop.

Fishing boats reflected in a still harbourHarbour
<Slideshow items={slides} getKey={(s) => s.title} label="Recent work" arrows="none" dots slideClassName="w-[78%] sm:w-[58%]" renderItem={(s) => <SlideCard slide={s} />} />

Installation

$ npx shadcn@latest add https://framebrick.co/r/slideshow.json

Usage

import { Slideshow } from "@/components/ui/slideshow";

<Slideshow
  items={projects}
  getKey={(p) => p.slug}
  label="Recent work"
  slideClassName="w-[78%] sm:w-[58%]"
  renderItem={(p) => <ProjectCard project={p} />}
/>

// a dot per slide under the frame (Catchup's testimonials)
<Slideshow items={quotes} getKey={(q) => q.name} label="Testimonials" arrows="none" dots renderItem={(q) => <Quote quote={q} />} />

Props

PropTypeDefaultDescription
itemsT[]—The slides' data.
renderItem(item, index) => ReactNode—Renders one slide.
getKey(item, index) => string—Stable key per item.
labelstring—Accessible name of the carousel.
intervalnumber5000Milliseconds between slides; 0 turns autoplay off.
pauseOnHoverbooleantrueStop autoplay while the pointer is over it. False keeps it going, as the Lookis testimonials do; focus and dragging still pause it.
gapnumber16Space between slides, in px.
perViewnumber | { base?, sm?, md?, lg? }1How many slides are in view at once (Denzel: 4, 2 and 1, 30 px apart). An object gives one number per width of the slideshow itself (sm 576 px, md 768 px, lg 1024 px), each carrying on from the one before. Without slideClassName each slide is (100% - the gaps) / perView wide. All slides in view: it holds still.
loopbooleantrueWrap round at the ends. false stops at the first and the last slide: one copy of the slides, the arrow at an end fades and is disabled (Fitbricks), and autoplay stops at the last slide.
dragbooleantrueWhether the pointer can drag it. False (Denzel's) leaves the arrows, the dots and the arrow keys.
run"auto" | "hover""auto"auto plays on its own. hover stands on the first slide and steps every interval only while the pointer or the keyboard focus is on the slideshow, or on the ancestor hoverTarget names, then goes back to the first slide at once (Goeboek's property card). pauseOnHover is ignored with it.
hoverTargetstring—With run="hover": a selector for the nearest ancestor whose hover and focus start it (".group"), the same as Marquee's. Itself when left out.
arrows"inside" | "below-left" | "sides" | "above" | "none""inside"Where the arrows sit: over the bottom right of the frame, under it on the left, one on each side of the frame halfway down (Goeboek, Findit: shown while the pointer is over it or an arrow has the focus, always on a touch screen), a small pair in a row above the frame at the right (Kendi), or nowhere.
dotsboolean | "inside"falseA row of dots, one per slide. true puts it under the frame; "inside" puts it over the foot of the frame, 10 px up, in a small pill of the page colour at 80% so the dots hold 3:1 over a dark photo (Goeboek). Under the frame, one per slide: the current one at full opacity, the others at half. With arrows="below-left" the arrows sit on the left of the same row and the dots on the right.
slideClassNamestring—Width of one slide — under 100% the next slide peeks in.
dotsClassNamestring—Classes for the row of dots: an offset, an alignment, a pill behind them.
  • loop={false} is Fitbricks' testimonial carousel: a row with two ends. One copy of the slides, no wrapping, the slide on show stops at the first and at the last (the last one that leaves no empty room when several are in view), and an arrow at an end fades and is disabled, so it cannot be pressed and Tab skips it. Dragging past an end springs back; the dots, the keys and run="hover" work as before, and autoplay stops at the last slide instead of going round. Fitbricks scrolls a native scroll-snap row by touch and presses the arrow to 0.9; here it is dragged and has the same arrows as the looping one, one code for both. The default, true, is as it was.
  • arrows="above" is Kendi's "Inspiration" slideshow: two small round arrows, 25 px and 10 px apart, in a row above the frame at the right, always shown, with two slides in view (one on a phone). Kendi puts them 50 px above the slides, over a heading; here the row sits 12 px above the frame, and a heading above is yours to place. Same names and bg-background/80 as the others.
  • arrows="sides" is Goeboek's hero (and Findit's carousel, which keeps them always on): a round 40 px arrow on each side, 20 px from the edge, halfway down, shown while the pointer is over the slideshow or an arrow has the focus (Framer: full opacity within 0.1 s, gone 0.1 to 0.3 s after the pointer leaves; here a 150 ms fade, which motion-reduce turns off). A touch screen has no hover, so they are always there. A hidden arrow stays in the Tab order and shows when it is reached, so the focus is never on something unseen. Same names and bg-background/80 as the others.
  • dots="inside" is Goeboek's hero (10 px up from the foot) and property card (8 px dots, 5 px up): the same buttons in the same row, in a small pill of bg-background/80 so the inactive dots keep 3:1 over a dark photo, and no row under the frame. true and false are as they were; dotsClassName still places and styles the row.
  • run="hover" is Goeboek's property card, whose photo turns through its pictures only while the card is pointed at (measured: the first step after about 1.5 s, then every 1.5 s, spring 200 / 40 / 1, and back to the first picture at once when the pointer leaves). It stands on the first slide, steps every interval while the pointer (a mouse or a pen) or the keyboard focus is on the slideshow, or on the ancestor hoverTarget names, and goes back to the first slide with no movement when they leave. Like autoplay it never runs for a visitor who asked for reduced motion (Framer's does; this and Goeboek's port stand still): the dots and arrows still move it. The hidden slides stay inert and aria-hidden, so at rest only the first is reachable, and the markup the server sends does not depend on hover.
  • perView and drag are Denzel's slider, which already had this component's numbers (5000 ms, spring 200 / 40 / 1, no arrows, no pause on hover): 4, 2 and 1 slides in view, 30 px apart, and a row that cannot be dragged. The slide on show and the ones after it, as many as are in view, are neither aria-hidden nor inert, so three visible cards are read and reached with Tab, which a carousel that hid all but one would not allow. The number in view is read from CSS after layout (the breakpoints are the slideshow's own width, a container query), so the markup the server sends never depends on it; the default, 1, is the carousel as it was. When every slide is in view it holds still: one copy of each, no autoplay, no drag, the arrows do nothing.
  • The slideshow is its own named carousel region (role region, aria-roledescription carousel, aria-label from label): a section around it must not carry the same name, or axe reports landmark-unique. Give the section no label, or a different one.
  • Autoplay pauses while the slideshow is hovered (unless pauseOnHover is false), focused, dragged or scrolled out of view.
  • The Lookis testimonials are this component: interval 4000, spring 200 / 40 / 1, pauseOnHover false, and the arrows over the bottom right of the frame, which is arrows="inside".
  • It never auto-plays for a visitor who asked for reduced motion — a timer is not a transform, so MotionConfig would not stop it.
  • Drag or swipe to move; ← and → move one slide when the carousel has focus.
  • The slides that are not current are inert as well as aria-hidden, so Tab cannot reach a link inside one.
  • The dots are Catchup's progress dots on the testimonials' carousel: 10 px dots, the current one at full opacity and the others at 50 %. Catchup draws one per page of its scroll-snap row (3 at 810 px, 5 at 390); this slideshow moves one slide at a time, so it has one dot per slide. A dot goes to its slide the shorter way round the loop, and with one slide there are no dots.
  • Each dot is a 24 px button round the 10 px dot (WCAG 2.5.8), named "Go to slide n", with aria-current on the current one, in a group named "Choose a slide". The others are foreground at 50 %: 3.2:1 or better against the page in the four sample themes, light and dark (3.15 on a muted surface at worst), above the 3:1 a control needs. Check your own colours before you rely on it.

AI prompt

Paste into v0, Lovable, Bolt or Claude to rebuild this component in your own project.

Create a React + Tailwind CSS + Motion (motion/react) component called Slideshow — an infinite carousel.
- Render three copies of the items in a flex track; keep an index starting in the middle copy, animate the track's x
  motion value to -index * step with a spring (stiffness 200, damping 40, mass 1), and when the index passes either end,
  jump silently back into the middle copy (x.jump) and reset the index.
- step = slide width + gap, measured with a ResizeObserver on the track.
- Autoplay every `interval` ms, paused while hovered (mouse only; a pauseOnHover prop, true by default, turns that off),
  focused, dragged, or out of view (useInView 0.3).
- drag="x" with dragMomentum false; on drag end, advance if the offset is over 20% of a slide or the velocity over 500,
  otherwise spring back.
- Arrow buttons bottom-right: size-8 rounded-full border bg-background/80 shadow-sm.
- Accessibility: role region, aria-roledescription carousel, aria-label, tabIndex 0 with ArrowLeft/ArrowRight,
  aria-hidden on slides that are not current.
- A dots prop (false by default) adds a row under the frame, centred, one button per item (none when there is one item):
  a size-6 button (a 24px target) round a size-2.5 rounded-full bg-foreground dot, at opacity 50% unless it is the current
  slide (index % count). aria-label "Go to slide n", aria-current="true" on the current one, the row a role group named
  "Choose a slide". A dot goes to its slide by the shorter way round: delta = slide - current, minus count when it is over
  count / 2, plus count when it is under -count / 2, added to the index. With arrows "below-left" the arrows sit on the
  left of that row and the dots on the right.
- perView (a number or { base, sm, md, lg }, default 1; each carrying on from the one before) and drag (default true). The track gets inline custom properties --per-base, --per-sm, --per-md, --per-lg and --gap, and the classes [--per:var(--per-base)] @xl:[--per:var(--per-sm)] @3xl:[--per:var(--per-md)] @5xl:[--per:var(--per-lg)] on an @container root, so --per is the number in view at the slideshow's own width. Without a slideClassName each slide is w-[calc((100%-(var(--per)-1)*var(--gap))/var(--per))]. Read --per from getComputedStyle in the same layout effect that measures the step and keep it in state (starting at the base number, so the server markup does not depend on it). Slides from the current index to index + visible - 1 are not aria-hidden or inert. When every slide is in view (count <= visible, with perView set): render one copy, x 0, no autoplay, no drag, arrow keys do nothing. drag false sets drag off and drops the grab cursor.
- loop (default true): false renders one copy of the slides, starts at index 0, clamps the index to 0 and count - visible (every place that changes it goes through one clamped setter), never does the loop jump, and gives the arrows disabled at an end (disabled:opacity-40 disabled:cursor-default); the dots go straight to a slide; autoplay stops at the last slide because the index no longer changes.
- arrows="above": a row (mb-3 flex justify-end gap-2.5) before the frame holding the two arrows at size-[25px]; always shown.
- arrows="sides": a pointer-events-none overlay (absolute inset-x-5, top 50%, -translate-y-1/2, flex justify-between) over the frame holding two size-10 pointer-events-auto round arrows; where hover is available ([@media(hover:hover)]) they are opacity-0 and go to 1 on group-hover and group-focus-within of the root (a group), with a 150ms opacity transition that motion-reduce turns off; on a touch screen they stay visible. They stay focusable.
- dots="inside": the same row of dot buttons in an absolute inset-x-0 bottom-2.5 overlay, centred, inside a rounded-full bg-background/80 px-1 pill (backdrop-blur-sm); no row under the frame (only dots === true draws that one).
- run ("auto" | "hover", default "auto") and hoverTarget: with hover the slideshow stands on the first slide and the autoplay timer only runs while the pointer (not touch) or the keyboard focus is on the root or on the ancestor root.closest(hoverTarget); pauseOnHover is ignored. When they leave, set the index back to the first slide and jump the track there (x.jump, a flag the animate effect reads) with no movement. Reduced motion never autoplays.

Be the first to know

Get new templates and components first

One short email when we release a template or a free component. No spam — unsubscribe anytime.

We use your email only for Framebrick updates. Privacy policy