react-carousel-ts
TypeScript icon, indicating that this package has built-in type declarations

3.0.1 • Public • Published

React-carousel- ts

npm bundle size License: MIT

Ultra-light carousel component for React

About

This carousel provides infinite scrolling without cloning elements, ensuring efficient memory use and performance. It leverages requestAnimationFrame for smooth animations, optimizing performance and reducing CPU load.

Installation

Install the package using npm:

npm i -D react-carousel-ts

Basic Usage

First, import the Carousel component and ensure you include the necessary CSS file for styling:

import { Carousel } from 'react-carousel-ts';
import 'carousel.css';

export const MyComponent = () => {
  const data = [
    <div className="example">1</div>,
    <div className="example">2</div>,
    <div className="example">3</div>,
  ];

  return <Carousel items={data} className="carousel" />;
};

To ensure the carousel displays correctly, it's important to include CSS styles for sizing, borders, and other visual aspects.

.carousel {
  height: 40vh;
  width: 50vw;
  border: 2px solid white;
  border-radius: 14px;
}

[!IMPORTANT]

  • The carousel requires at least three elements to function properly with all transition effects.
  • With only two elements, only the FADE and SCALE transition effects will function correctly.
  • If there is only one or no elements, the carousel will not be displayed.

Infinity scrolling

To enable the infinite scrolling effect in the Carousel component, simply set the infinity property to true.

<Carousel infinity={true} />

This will allow the carousel to loop through items endlessly.

Setting the number of visible elements

To control the number of items displayed at once in the Carousel, use the visibleItemCount property.

<Carousel visibleItemCount={2} />

Customizing Arrows and Dots

You can control their visibility, position, size, and color to match the design of your application.

import { Carousel, CarouselProps, ArrowPosition, DotsTheme } from 'react-carousel-ts';
import 'carousel.css';

export const MyComponent = () => {
  const data = [
    <div className="example">1</div>,
    <div className="example">2</div>,
    <div className="example">3</div>,
  ];

  const props: CarouselProps = {
    className: 'carousel',
    // The size of the arrow in vh/vw units. Default value is 8.
    arrowSize: 8,

    // The color of the arrow. It can be one of the predefined colors or in RGB, RGBA, HEX format.
    arrowColor: 'gray',

    // The position of the arrow. It can be INSIDE, OUTSIDE, or BORDER.
    arrowPosition: ArrowPosition.BORDER,

    // Whether to show dots. Default value is false.
    showDots: true,

    // The theme of the dots. It can be LINE, ROUND, or RECTANGLE.
    dotsTheme: DotsTheme.LINE,

    // The color of the dots. It can be one of the predefined colors or in RGB, RGBA, HEX format.
    dotsColor: 'gray',
  };

  return <Carousel items={data} {...props} />;
};

Transition Effects

If moveEffect is not specified, a simple x-axis rotation is used. This can be changed using the moveEffect prop Currently, MoveEffect has three values: PERPETUAL_AD_SCROLL(Continuous scrolling effect), FADE(fade in and out), SCALE(scale up and down)

import { Carousel, CarouselProps, MoveEffect } from 'react-carousel-ts';
import 'carousel.css';

export const MyComponent = () => {
  const data = [
    <div className="example">1</div>,
    <div className="example">2</div>,
    <div className="example">3</div>,
  ];

  return <Carousel items={data} moveEffect={MoveEffect.SCALE} />;
};

Props

Name Type Default Description
items ReactNode[] [] Carousel items.
showDots boolean false Shows navigation dots.
showArrows boolean true Shows navigation arrows.
speed number 1000 Transition speed in ms.
autoplay boolean false Enable automatic cycling.
infinity boolean false Enables infinite cycling of carousel items.
autoplaySpeed number 4000 Autoplay interval (ms).
moveEffect MoveEffect undefined Slide transition effect. (Possible values: FADE, SCALE, PERPETUAL_AD_SCROLL)
visibleItemCount number 1 Visible items count.
arrowPosition ArrowPosition INSIDE Arrow position.
arrowSize number 7 Size of the navigation arrows.
arrowColor CarouselControlColor white Arrow color. (Possible values: Any valid CSS color value)
dotsTheme DotsTheme RECTANGLE Shape of the navigation dots. (Possible values: ROUND, RECTANGLE, LINE)
dotsColor CarouselControlColor white Dots color. (Possible values: Any valid CSS color value)
className string '' Additional CSS class.

TODO

  • [ ] Add support for custom arrows and dots
  • [ ] Add support custom transition effects

Contact Information

Package Sidebar

Install

npm i react-carousel-ts

Weekly Downloads

9

Version

3.0.1

License

MIT

Unpacked Size

33.1 kB

Total Files

32

Last publish

Collaborators

  • suwaloff