React-circular-carousel-ts NPM

: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

Props

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

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.