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