Strongly typed circular carousel for React

Table of contents

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

Installation

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

Features

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

Overview

🏆 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

💰 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