PixoraCarousel

PixoraCarousel is a highly customizable React carousel component that offers seamless autoplay, looping, and thumbnail navigation. Designed to create flexible and responsive image carousels, it provides a smooth user experience with minimal setup.

Showcase

Web

Bottom Thumbnail Position

Left Thumbnail Position

Mobile

Bottom Thumbnail Position	Left Thumbnail Position

Installation

Using npm:

1npm install react-pixora-carousel

Using Yarn:

1yarn add react-pixora-carousel

Usage

1import PixoraCarousel from "react-pixora-carousel";
2
3const images = [
4  {
5    src: "https://picsum.photos/500/500?random=1",
6  },
7  {
8    src: "https://picsum.photos/500/500?random=2",
9  },
10  {
11    src: "https://picsum.photos/500/500?random=3",
12  },
13  {
14    src: "https://picsum.photos/500/500?random=4",
15  },
16  {
17    src: "https://picsum.photos/500/500?random=5",
18  },
19  {
20    src: "https://picsum.photos/500/500?random=6",
21  },
22  {
23    src: "https://picsum.photos/500/500?random=7",
24  },
25];
26
27const App: React.FC = () => {
28  return (
29    <div className="h-svh flex flex-col justify-center items-center">
30      <PixoraCarousel
31        images={images}
32        loop={true}
33        containerClassName="h-[50%]! md:h-full!"
34        thumbnailPosition="left"
35      />
36    </div>
37  );
38};
39
40export default App;

Usage with Tailwind CSS

When using Tailwind CSS, you can apply the ! prefix to a utility class to force override the default styles and ensure that your custom styles take precedence.

For detailed information, check out the Tailwind CSS documentation on using the ! prefix for overriding styles.

Props

Prop	Type	Default	Description
images	Image[]	Required	Array of image objects, where each object contains a src (required) and an optional alt text. Example: { src: "image-url", alt: "image description" }.
loop	boolean	false	Enables looping of carousel items.
autoPlay	boolean	false	Enables or disables autoplay.
stopOnInteraction	boolean	false	Stops autoplay on user interaction.
autoPlayDelay	number	3000	Time in milliseconds between slide transitions.
thumbnailPosition	string	"bottom"	Position of the thumbnails. Can be "bottom", "left", "right", or "top".
onSelectThumb	function	undefined	Callback function when a thumbnail is selected, receiving the image: { src: string, alt:string } and index: number as arguments.
containerClassName	string	container	Custom class for the main container.
containerStyle	object	undefined	Inline styles for the main container.
hideThumbnails	boolean	false	Hides the thumbnails in the carousel.
hideThumbnailsOnMobile	boolean	false	Hides the thumbnails on mobile devices.

Carousel Props

Prop	Type	Default	Description
carouselContainerClassName	string	carousel-container	Custom class for the carousel container.
carouselContainerStyle	object	undefined	Inline styles for the carousel container.
carouselSlideClassName	string	carousel-slide	Custom class for individual carousel slides.
carouselSlideStyle	object	undefined	Inline styles for individual carousel slides.
carouselImageClassName	string	carousel-image	Custom class for carousel images.
carouselImageStyle	object	undefined	Inline styles for carousel images.
carouselOverlay	ReactNode | () => ReactNode	undefined	Renders content over the carousel.

Thumbnail Props

Prop	Type	Default	Description
thumbnailWrapperClassName	string	thumbnail-wrapper	Custom class for the thumbnail wrapper.
thumbnailWrapperStyle	object	undefined	Inline styles for the thumbnail wrapper.
thumbnailContainerClassName	string	thumbnail-container	Custom class for the thumbnail container.
thumbnailContainerStyle	object	undefined	Inline styles for the thumbnail container.
thumbnailButtonClassName	string	thumbnail-button	Custom class for the thumbnail button.
thumbnailButtonStyle	object	undefined	Inline styles for the thumbnail button.
thumbnailButtonSelectedClassName	string	thumbnail-button.selected	Custom class for the selected thumbnail button.
thumbnailButtonSelectedStyle	object	undefined	Inline styles for the selected selected thumbnail button.
thumbnailImageClassName	string	thumbnail-image	Custom class for the thumbnail image.
thumbnailImageStyle	object	undefined	Inline styles for the thumbnail image.
thumbnailOverlay	ReactNode | () => ReactNode	undefined	Renders content over the thumbnails.

Default Styles

PixoraCarousel provides default styles for various elements to ensure a seamless experience. You can override these styles using the provided props.

Container

1container {
2  max-width: min(800px, 100vw);
3  max-height: min(750px, 100svh, 100vh);
4  padding: 16px;
5  display: flex;
6  gap: 16px;
7  width: 100%;
8  height: 100%;
9}

Carousel

1carousel-container {
2  overflow: hidden;
3  display: flex;
4  width: 100%;
5  height: 100%;
6}
7
8carousel-slide {
9  flex: 0 0 100%;
10  min-width: 0;
11  margin-right: 8px;
12  position: relative;
13  display: flex;
14  justify-content: center;
15  align-items: center;
16  border-radius: 8px;
17}
18
19carousel-image {
20  height: 100%;
21  width: 100%;
22  object-fit: cover;
23  border-radius: 8px;
24}

Thumbnail

1thumbnail-wrapper {
2  overflow: hidden;
3  flex-shrink: 0;
4}
5
6/* Hide thumbnails on mobile devices if hideThumbnailsOnMobile Prop is true */
7@media (max-width: 480px) {
8  thumbnail-wrapper.hidden {
9    display: none;
10  }
11}
12
13thumbnail-container {
14  display: flex;
15  gap: 8px;
16  justify-content: start;
17  max-height: 100%;
18}
19
20thumbnail-button {
21  cursor: pointer;
22  opacity: 0.7;
23  flex-shrink: 0;
24  width: 120px;
25  height: 120px;
26  border-radius: 8px;
27  position: relative;
28  overflow: hidden;
29}
30
31/* Adjust thumbnail button size for tablet screens */
32@media (max-width: 768px) {
33  thumbnail-button {
34    width: 90px;
35    height: 90px;
36  }
37}
38
39/* Adjust thumbnail button size for small mobile screens */
40@media (max-width: 480px) {
41  thumbnail-button {
42    width: 70px;
43    height: 70px;
44  }
45}
46
47thumbnail-button:hover {
48  opacity: 1;
49}
50
51thumbnail-button.selected {
52  opacity: 1;
53  border: 2px solid;
54  border-color: #3b82f6;
55  border-radius: 8px;
56}
57
58thumbnail-image {
59  width: 100%;
60  height: 100%;
61  object-fit: cover;
62}

License

MIT