react-tiny-image-carousel

A tiny accessible React image carousel component with TypeScript types, arrows, dots, autoplay, keyboard navigation, touch swipe, and plain responsive CSS.

Lightweight

The package is intentionally small:

• Around 5.9 KB packed
• Around 15.2 KB unpacked
• Around 1.36 KB gzip for the ESM build
• Around 1.04 KB gzip for the default CSS

React is a peer dependency, so it is not bundled into this package. Demo images are not published because the package only ships the dist output.

Install

yarn add react-tiny-image-carousel

npm install react-tiny-image-carousel

Usage

import { Slider, type SliderImage } from 'react-tiny-image-carousel'
import 'react-tiny-image-carousel/style.css'

const slides: SliderImage[] = [
  {
    src: '/images/product-1.jpg',
    alt: 'Product preview from the front',
    caption: 'Front view',
  },
  {
    src: '/images/product-2.jpg',
    alt: 'Product preview from the side',
    caption: 'Side view',
  },
]

export function Gallery() {
  return <Slider slides={slides} autoplay interval={4000} />
}

Examples

The web demo uses local images from src/assets/demo-slides. Replace those files or import your own images in src/App.tsx when customizing the demo.

Autoplay:

<Slider slides={slides} autoplay interval={3000} />

Manual:

<Slider slides={slides} />

No loop:

<Slider slides={slides} loop={false} />

Minimal:

<Slider slides={slides} showArrows={false} showDots={false} />

Standalone without captions:

const slidesWithoutCaptions = slides.map(({ src, alt }) => ({ src, alt }))

<Slider slides={slidesWithoutCaptions} />

Props

Prop	Type	Default	Description
slides	SliderImage[]	Required	Image data for the slider.
initialIndex	number	0	First slide to show.
loop	boolean	true	Wrap at the first and last slide.
autoplay	boolean	false	Advance slides automatically.
interval	number	5000	Autoplay delay in milliseconds. Minimum runtime delay is 1000ms.
showArrows	boolean	true	Show previous and next buttons.
showDots	boolean	true	Show slide picker dots.
className	string	undefined	Extra class for the root element.
ariaLabel	string	'Image slider'	Accessible label for the slider region.
onSlideChange	(index: number) => void	undefined	Called after the active slide changes.

type SliderImage = {
  src: string
  alt: string
  caption?: string
}

Accessibility

• Arrow Left and Arrow Right move between slides.
• Home and End jump to the first and last slide.
• Touch and pointer swipes move between slides on mobile devices.
• Autoplay pauses while the slider is hovered or focused.
• Image alt text is required in the SliderImage type.
• Dot controls expose tab state with aria-selected.

Styling

Import the default stylesheet:

import 'react-tiny-image-carousel/style.css'

The CSS uses srs- prefixed classes and a few custom properties on the root element:

.my-slider {
  --srs-radius: 6px;
  --srs-focus: #2563eb;
  --srs-control-bg: rgba(15, 23, 42, 0.72);
}

<Slider className="my-slider" slides={slides} />

Full-width custom example:

.featured-slider {
  --srs-radius: 8px;
  --srs-arrow-size: 48px;
  width: 100%;
}

.featured-slider .srs-viewport {
  aspect-ratio: 21 / 9;
}

@media (max-width: 640px) {
  .featured-slider {
    --srs-arrow-size: 40px;
  }

  .featured-slider .srs-viewport {
    aspect-ratio: 4 / 3;
  }
}

<Slider className="featured-slider" slides={slides} autoplay />

Development

yarn install
yarn dev
yarn lint
yarn build

yarn build emits:

• dist/react-tiny-image-carousel.js for ESM
• dist/react-tiny-image-carousel.cjs for CommonJS
• dist/style.css for default styles
• dist/types for TypeScript declarations