Strongly typed circular carousel for React

Table of contents

• :dart: Installation
• :dart: Features
• :dart: Overview
• :dart: Demo
• :dart: Props
• :dart: Exports
• :dart: Framework Usage - (SSR)
• :dart: Compatibility
• :dart: Recipes
• :dart: Layout
• :dart: Typescript SuperPowers
• :dart: Open an issue
• :dart: Contact/About author

Installation

• npm - npm i react-circular-carousel-ts
• yarn - yarn add react-circular-carousel-ts

Features

• :star: Offering 2 and 3 dimensional designs
• :star: Configure your carousel look and feel with a range of built in props
• :star: Provide your own slide components
• :star: Customize your carousel by extending your own styles and classNames
• :star: Choose from a selection of Framer Motion Transitions
• :star: Utilize on-change event handlers
• :star: Enjoy optimized animations (Hardware acceleration) courtesy of Framer Motion
• :star: Enjoy cross device compatibility ( click or swipe! )
• :star: Enjoy window resize re-rendering support
• :star: Benefit from comprehensive type checking during development, get type safety on your content!
• :star: Compatible in standard JS and TS environments
• :star: Offering throttled movement for UX consistency

Overview

:trophy: This package is simply a thin content agnostic wrapper that wraps around your slides, so that you can focus on creating content, while it handles the rest! 🏖️🥂

See a Demo

• Homepage

• Storybook

Props

Exports

FramerTransitions

export enum FramerTransitions {
  tween = "tween",
  spring = "spring",
}
// For standard JS environments simply use the string values eg ( "tween" | "spring" )

import { FramerTransitions } from "react-circular-carousel-ts/types";

CarouselTypes

export enum CarouselTypes {
  STANDARD_2D = "standard",
  STANDARD_3D = "standard3D",
}

// For standard JS environments simply use the string values eg ( "standard" | "standard3D" )

import { CarouselTypes } from "react-circular-carousel-ts/types";

useCircularCarouselContext

type CircularCarouseContextProps = {
  media: MediaProps;
  action: Actions;
  setAction: Dispatch<SetStateAction<Actions>>;
  setMedia: Dispatch<SetStateAction<MediaProps>>;
  activeIdx: number;
  animationType: FramerTransitions;
  slideWidth: number;
  slideGap: number;
  aspectRatio: `${string}/${string}`;
  handleNext: () => void;
  handlePrev: () => void;
  innerCarouselWidth: number | undefined;
  setInnerCarouselWidth: Dispatch<SetStateAction<number>>;
  isDynamic: boolean;
};

import { useCircularCarouselContext } from "react-circular-carousel-ts";

Carousel

function CircularCarouselComponent<T>(props: PropsWithChildren<CircularCarouselWrapperProps<T>>): ReactNode

import { Carousel } from "react-circular-carousel-ts";

Context

With useCircularCarouselContext you can:

• Assign movement control functions to your custom controls
• Track the active slide id, great to use when you want to render your own indicators
• For examples please see the Recipes section

import { useCircularCarouselContext } from "react-circular-carousel-ts";

Framework Usage

Next.js

In future iterations there will be SSR compatibility

// Your page
import dynamic from 'next/dynamic'
const Carousel = dynamic(() => import('<pathToCarousel>'), {
ssr: false
})
export default function Home() {
return (
<main>
<Carousel />
</main>
);
}

Create a carousel module - NB add "use client" at the top

"use client"
// omitted imports for brevity

// omitted code for brevity

export default function DefaultCarousel() {
    return (
        <main className={styles.main}>
            <div style={{ width: "100%" }}>
                <Carousel
                    type={CarouselTypes.STANDARD_3D}
                    slideComponent={CustomSlideComponent}
                    mediaPool={custom}
                    slideClassName="my-slide"
                    aspectRatio="2/1"
                    animationType={FramerTransitions.TWEEN}
                >
                </Carousel>
             </div>
        </main>
    );
}

create-react-app projects

Not supported currently, unlikely to support this project environment as its deprecated.

Known Compatibility

Package lists the following peerDependencies:

"peerDependencies": {
    "react": ">=18.0.0",
    "react-dom": ">=18.0.0"
  }

NB - Compatibility includes but is not limited to

• react: ^18.0.0

• webpack: ^5.91.0

• storybook: ^8.1.3

• @types/react: ^18.0.0

• @types/react-dom: ^18.0.0

• typescript: ^5.0.0

• @types/node: ^20.0.0

• next: 14.2.5

• react: ^18.0.0

• react-dom: ^18.0.0

• vite": ^5.1.4

• Node versions -- v14.21.3 -- v16.20.2 -- v18.19.0

Recipes

With Custom Controls

import {CustomSlideComponent. customData} from "."
import { CarouselTypes } from "react-circular-carousel-ts/types"
import { useCircularCarouselContext } from "react-circular-carousel-ts"
const TILE_WIDTH = Math.floor(window.innerWidth * 0.3)
const CustomControls = () => {
const { handleNext, handlePrev } = useCircularCarouselContext()
return (
<div>
<button onClick={handlePrev}>Previous</button>
<button onClick={handleNext}>Next</button>
</div>
)
}
const WithCustomControls = () => <Carousel
type={CarouselTypes.STANDARD_2D}
slideComponent={CustomSlideComponent}
slideWidth={TILE_WIDTH}
slideGap={50}
mediaPool={customData}
onChange={(args) => console.log(args)}
customControls={true}
aspectRatio={"1/1"}
>
<CustomControls />
</Carousel>

Three Dimensional

import {CustomSlideComponent. customData} from "."
import { CarouselTypes } from "react-circular-carousel-ts/types"
const ThreeDimensional = () => <Carousel
mediaPool={customData}
type={CarouselTypes.STANDARD_3D}
slideComponent={CustomSlideComponent}
aspectRatio={"1/2"}
/>

With Dynamic Slide Width

import {CustomSlideComponent. customData} from "."
import { CarouselTypes } from "react-circular-carousel-ts/types"
const WithDynamicSlideWidth= () => <Carousel
type={CarouselTypes.STANDARD_2D}
mediaPool={customData}
slideWidth={100}
dynamicWidth={true}
slideGap={50}
slideComponent={CustomSlideComponent}
aspectRatio='3/1'
/>

Custom Icons

import {CustomSlideComponent. customData, NextIcon, PrevIcon, CustomSlideComponentProps} from "."
import { CarouselTypes } from "react-circular-carousel-ts/types"
const CustomSlideComponent: FC<CustomSlideComponentProps> = (props) => {
return (
<div>
<img
src={props.avatar} alt="avatar for slide" />
</div>
)
}
const WithCustomIcons = () => <Carousel
type={CarouselTypes.STANDARD_2D}
mediaPool={customData}
slideWidth={100}
dynamicWidth={true}
slideGap={50}
slideComponent={CustomSlideComponent}
aspectRatio='3/1'
nextIcon={<NextIcon />}
prevIcon={<PrevIcon />}
/>

Layout

In order to ensure your carousel layout looks optimal, ensure at any given time the amount of slides is sufficient

:moneybag: TIP If your slide count is low, double or triple it with Javascript ( You may want to hide the indicators since your slide collection will contain duplicates.) It is not recommended to render the 3D carousel on mobile, as it implements a fixed slide sizing algorithm.

Typescript SuperPowers

Props mediaPool and slideComponent are type coupled thanks to TS generics! If you are using this package in TS environment (recommended!)🎖️

Open an issue