Swiper

Updated: October 18, 2025

An interactive carousel that uses native CSS scroll-snap for smooth, performant scrolling. Features native touch/swipe gestures on mobile and drag-to-scroll on desktop for seamless navigation between slides.

Swiper

<Swiper
  items={[
    { slide: "/images/1.jpg", alt: "Image 1" },
    { slide: "/images/2.jpg", alt: "Image 2" },
  ]}
/>

Interactions

The Swiper uses native CSS scroll-snap, providing smooth touch gestures on mobile, trackpad scrolling, and mouse drag-to-scroll on desktop. Simply click and drag to navigate between slides.

Interactions

<Swiper
  items={[
    { slide: "/images/1.jpg", alt: "Image 1" },
    { slide: "/images/2.jpg", alt: "Image 2" },
    { slide: "/images/3.jpg", alt: "Image 3" },
  ]}
/>

Indicators

By default, the Swiper displays dot indicators below the carousel. The active dot is highlighted and slightly scaled for better visibility.

Indicators

<Swiper
  indicator={true}
  items={[...]}
/>

<Swiper
  indicator={false}
  items={[...]}
/>

Controls

The controls prop supports three options: true (appear on hover), false (hidden), or "contained" (always visible inside the carousel). Buttons are automatically hidden when at the first or last slide.

Controls

<Swiper
  controls={true} // Appear on hover
  items={[...]}
/>

<Swiper
  controls="contained" // Always visible
  items={[...]}
/>

<Swiper
  controls={false} // Hidden
  items={[...]}
/>

Aspect ratio

Customize the aspect ratio of the carousel to fit your design needs. Supports standard aspect ratio values.

Aspect ratio

<Swiper
  aspectRatio="16 / 9"
  items={[...]}
/>

<Swiper
  aspectRatio="4 / 3"
  items={[...]}
/>

<Swiper
  aspectRatio="1 / 1"
  items={[...]}
/>

Custom content

You can place custom content inside the slides as ReactNode, not just images.

Custom content

Slide 1

Slide 2

Slide 3

<Swiper
  items={[
    { slide: <Row fill center background="brand-strong"><Text>Slide 1</Text></Row> },
    { slide: <Row fill center background="accent-strong"><Text>Slide 2</Text></Row> },
    { slide: <Row fill center background="neutral-strong"><Text>Slide 3</Text></Row> },
  ]}
/>

API Reference

Prop	Type	Default
itemsrequired The slides, each with its source and alt text.	SwiperItem[]	[]
controls Show the chevrons. "contained" keeps them inside the frame.	booleancontained	true
priority Load the first slide eagerly, for one above the fold.	boolean	false
stretch Drop the intrinsic ratio and take sizing from the parent instead.	boolean	false
aspectRatio Frame ratio, held as the width changes.	string	16 / 9
sizes The sizes attribute passed to the images.	string	—
unoptimized Skip the framework image optimizer.	boolean	false
indicator Show the dots under the slides.	boolean	true
…and every FlexProps prop	inherited	—

ComponentsStylePanel

ComponentsTable

Edit this page on GitHub

Built with curiosity by Lorant One and the Design Engineers Club