# react-fancy-circular-carousel

> Interactive circular carousel with image elements highly customisable as per the developer's needs

Latest version **1.1.0** (published 2026-11-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-fancy-circular-carousel
pnpm add react-fancy-circular-carousel
yarn add react-fancy-circular-carousel
bun add react-fancy-circular-carousel
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-11-19 |
| First published | 2023-03-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 37.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 30 |
| Author | Ninad Sutrave |
| Maintainers | ninadsutrave |
| Keywords | react, slider, carousel, image-slider |

## Links

- npm: https://www.npmjs.com/package/react-fancy-circular-carousel
- Repository: https://github.com/ninadsutrave/react-fancy-circular-carousel
- Homepage: https://carousel-demopage.netlify.app
- Issues: https://github.com/ninadsutrave/react-fancy-circular-carousel/issues
- npm.io page: https://npm.io/package/react-fancy-circular-carousel

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2026-11-19
- 1.0.8 — 2023-04-03
- 1.0.7 — 2023-04-03
- 1.0.6 — 2023-04-03
- 1.0.5 — 2023-03-31
- 1.0.4 — 2023-03-31
- 1.0.3 — 2023-03-30
- 1.0.2 — 2023-03-29
- 1.0.1 — 2023-03-29
- 1.0.0 — 2023-03-29
- 0.0.1 — 2023-03-29

## README

<div align="center"><p align="center"><a href="https://www.npmjs.com/package/react-fancy-circular-carousel"><img src="./src/assets/React.webp" alt="React Logo - Carousel UI Component" width="140px" /></a></p></div>

<h1 align="center">React Circular Carousel Component</h1>

## Features

Try the demo [here](https://carousel-demopage.netlify.app).

- Circular image carousel
- Everything you see is customisable
- Get focus element to add in your own components
- Images or any custom elements, keyboard and click navigation
- Smooth, easy to implement, fantastic UI

## Installation

    $ npm install react-fancy-circular-carousel

  Include the styles by importing FancyCarousel.css

  ```jsx
  import 'react-fancy-circular-carousel/FancyCarousel.css';
  ```

## Quickstart

### Parameters

| **Parameter** | **Type** | **Description** |
|:---|:---|:---|
| images | String[] | `mandatory` List of image sources (unless you pass children instead) |
| imageAlts | String[] | `optional` Alt text for each image, in the same order as `images` |
| children | React.ReactNode | `optional` Custom elements to place around the carousel instead of images |
| setFocusElement | Function | `optional` SetState method to get focus element in parent component |
| offsetAngle | Number | `optional` Angle in degrees to offset the carousel elements |
| carouselRadius | Number | `optional` Carousel radius in px |
| centralImageRadius | Number | `optional` Central image radius in px |
| centralImageBoxShadow | String | `optional` Central image box shadow property |
| peripheralImageRadius | Number | `optional` Peripheral Image radius in px |
| peripheralImageBoxShadow | String | `optional` Peripheral image box shadow property |
| focusElementStyling | React.CSSProperties | `optional` Custom styling for the element in focus |
| border | Boolean | `optional` Enable/disable bordering |
| borderWidth | Number | `optional` Border stroke width property in px |
| borderHexColor | String | `optional` Border hex color, with or without the '#' |
| autoRotateTime | Number | `optional` Time in seconds for an auto rotating carousel |
| pauseOnHover | Boolean | `optional` Pause auto rotation while hovered or focused with the keyboard (default true) |
| transitionTime | Number | `optional` Time in seconds for the rotating transition |
| navigationTextSize | Number | `optional` Arrow font size in rem |
| navigationButtonRadius | Number | `optional` Navigation button radius in px |
| navigationButtonColor | String | `optional` Arrow hex color, with or without the '#' |
| navigationButtonBgColor | String | `optional` Navigation button hex color, with or without the '#' |
| navigationButtonStyling | React.CSSProperties | `optional` Custom styling for navigation buttons |
| showNavigation | Boolean | `optional` Show the navigation buttons (default: shown unless auto rotating) |
| rotateOnClick | Boolean | `optional` Clicking an element rotates it into focus (default true) |
| responsive | Boolean | `optional` Fill the width of the parent element, scaling every size down to fit (never above the sizes given) |

### Usage

```jsx
import React from "react";

import FancyCarousel from "react-fancy-circular-carousel";
import 'react-fancy-circular-carousel/FancyCarousel.css';

import image1 from './assets/image1.png';
import image2 from './assets/image2.png';
import image3 from './assets/image3.png';
import image4 from './assets/image4.png';


const YourComponent = () => {

  const images = [image1, image2, image3, image4];

  return <div className="carousel">
    <FancyCarousel images={images} />
  </div>
};

export default YourComponent;
```

### Retrieve focus element

Utility using which one can know which element is currently at focus and may add relevant components around it. 
For eg. if the carousel portrays images of cities, this feature may help you update the description in the information box along side the carousel.

```jsx
import React, { useState } from "react";

import FancyCarousel from "react-fancy-circular-carousel";
import 'react-fancy-circular-carousel/FancyCarousel.css';

import image1 from './assets/image1.png';
import image2 from './assets/image2.png';
import image3 from './assets/image3.png';
import image4 from './assets/image4.png';

const YourComponent = () => {

  // the focus element would be the array index of the image currently at focus
  const [focusElement, setFocusElement] = useState(0);

  const images = [image1, image2, image3, image4];
  const info = ['Delhi', 'Mumbai', 'Bengaluru', 'Kolkata'];

  return <div className="carousel">
      <FancyCarousel images={images} setFocusElement={setFocusElement}/>
      <div className="info-box-wrapper">
        <p> {info[focusElement]} </p>
      </div>
    </div>
};

export default YourComponent;
```

### Keyboard and imports

The left and right arrow keys turn the carousel when it has keyboard focus. The component is also available as a named export, along with its props type:

```tsx
import { FancyCarousel, FancyCarouselProps } from "react-fancy-circular-carousel";
```

### Custom elements

Pass children instead of `images` to place your own elements around the carousel. Each child is clipped to a circle, and the element in focus is also shown in the centre, so it is rendered twice.

```jsx
import React from "react";

import FancyCarousel from "react-fancy-circular-carousel";
import 'react-fancy-circular-carousel/FancyCarousel.css';

const cities = ['Delhi', 'Mumbai', 'Bengaluru', 'Kolkata'];

const YourComponent = () => {

  return <div className="carousel">
    <FancyCarousel>
      {cities.map(city => (
        <div key={city} className="city-card">{city}</div>
      ))}
    </FancyCarousel>
  </div>
};

export default YourComponent;
```

### Customisations

Customise the carousel to your needs such as modifying the carousel size, image size, adding styling such as drop shadow, adding auto rotate, etc
The focusElementStyling and navigationButtonStyling props are of type React.CSSProperties, which is essentially a JavaScript object containing camelcased CSS properties and their corresponding values. 

To know more check the official documentation [here](https://legacy.reactjs.org/docs/dom-elements.html#style).

```jsx
import React from "react";

import FancyCarousel from "react-fancy-circular-carousel";
import 'react-fancy-circular-carousel/FancyCarousel.css';

import image1 from './assets/image1.png';
import image2 from './assets/image2.png';
import image3 from './assets/image3.png';
import image4 from './assets/image4.png';

const YourComponent = () => {

  const images = [image1, image2, image3, image4];

  return <div className="carousel">
    <FancyCarousel 
      images={images} 
      carouselRadius={400}
      peripheralImageRadius={100}
      centralImageRadius={200}
      focusElementStyling={{border: '2px solid #ba4949'}}
      autoRotateTime={3}
      borderWidth={4}
      borderHexColor={'1c364f'}
    />
  </div>
};

export default YourComponent;
```

## Preview

With navigators

![Preview Image](src/assets/preview1.png)

With auto rotation

![Preview Gif](src/assets/preview2.gif)

## NPM Module

[Npm Page](https://www.npmjs.com/package/react-fancy-circular-carousel)  
Try it out for yourselves and ⭐ this repo if you like it!

## License

MIT © [Ninad Sutrave](https://ninadsutrave.in)

---
_Source: https://npm.io/package/react-fancy-circular-carousel · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
