React Image Carousel

React image carousel library with a simple API, accessibility support and npm-ready packaging.

Features

• keyboard and screen-reader accessibility
• autoplay with pause on hover and focus
• optional loop mode
• arrows, indicators and thumbnail navigation
• swipe support for touch and pointer
• controlled and uncontrolled usage
• automated tests with coverage and CI

Installation

npm install react-best-carroussel react react-dom

Usage

import { ImageCarousel } from "react-best-carroussel";

const images = [
  { src: "/images/1.jpg", alt: "Landscape 1", caption: "First image" },
  { src: "/images/2.jpg", alt: "Landscape 2", caption: "Second image" },
  { src: "/images/3.jpg", alt: "Landscape 3", caption: "Third image" }
];

export function Gallery() {
  return <ImageCarousel images={images} autoplay showThumbnails aspectRatio="4 / 3" />;
}

Main props

• images: { src, alt, caption?, thumbnailSrc? }[]
• initialIndex, index, onIndexChange, onSlideChange
• loop, autoplay, autoplayDelay
• pauseOnHover, pauseOnFocus
• showArrows, showIndicators, showThumbnails
• keyboardNavigation, swipeThreshold
• aspectRatio, objectFit, labels

Quality

npm install --include=dev
npm run check

npm run check runs type checking, tests with coverage and the distribution build. The workflow in .github/workflows/ci.yml runs the same validation on push and pull request.

Release Automation

The workflow in .github/workflows/release.yml publishes the package to npm with Trusted Publishing when you push a tag matching v*.*.*.

Configure Trusted Publishing in npm for this GitHub repository using these values:

• Source repository owner: brujim
• Source repository name: react-best-carroussel
• Workflow file: .github/workflows/release.yml
• Environment: leave empty unless you later decide to use a protected GitHub environment

After the trusted publisher is configured on npm, you can release with:

git tag -a v0.1.1 -m "Release v0.1.1"
git push origin v0.1.1