@azfar_razzaq/react-infinite-carousel
Version:
This package provides a react component to render an infinite carousel
164 lines (117 loc) • 8.35 kB
Markdown
A customizable, responsive infinite carousel component for React applications. This package provides an easy way to create smooth, infinite-scrolling carousels that can display both images and text.
- 🔄 Smooth infinite scrolling animation
- 📱 Responsive design with customizable breakpoints
- 🖼️ Support for both images and text content
- ⚡ Auto-calculation of required clones to fill the viewport
- 🎮 Customizable animation speed and direction
- 🖱️ Interactive hover effects (speed up, slow down, or pause)
- 🌫️ Optional fade effect at the edges
- 📐 Flexible styling options
- 📦 TypeScript support with full type definitions
## Installation
```bash
npm install @azfar_razzaq/react-infinite-carousel
# or
yarn add @azfar_razzaq/react-infinite-carousel
```
## Usage
### Basic Image Carousel
```tsx
import Carousel from "@azfar_razzaq/react-infinite-carousel";
function App() {
const images = [
"https://example.com/image1.jpg",
"https://example.com/image2.jpg",
"https://example.com/image3.jpg",
];
return (
<Carousel itemType="images" images_links={images} durationPerClone={10} />
);
}
```
```tsx
import Carousel from "@azfar_razzaq/react-infinite-carousel";
function App() {
return (
<Carousel
itemType="text"
text="Your scrolling text here"
animationDirection="ltr"
hoverSpeedFactor={0.5}
/>
);
}
```
```tsx
import Carousel from "@azfar_razzaq/react-infinite-carousel";
function App() {
const responsiveConfig = [
{ breakpoint: 480, numOfCopies: 4 }, // up to 480px
{ breakpoint: 768, numOfCopies: 3 }, // 481-768px
{ breakpoint: 1024, numOfCopies: 2 }, // 769-1024px
];
return (
<Carousel
itemType="images"
images_links={images}
responsiveClones={responsiveConfig}
fade={50} // 50px fade effect at both edges
/>
);
}
```
These props are available for both image and text carousels:
| Prop | Type | Default | Description |
| -------------------- | ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `itemType` | `"images" \| "text"` | Required | Specifies whether the carousel displays images or text |
| `durationPerClone` | `number` | `10` | Time (in seconds) it takes one clone to travel the full carousel.The total loop duration is `durationPerClone × numberOfClones`, so the apparent speed remains constant even when the clone count changes with viewport width. |
| `numOfCopies` | `number` | Automatically calculated based on the current viewport width. | Base number of copies to display. The actual number of clones will be doubled (e.g., if set to 3, total clones will be 6) |
| `responsiveClones` | `Array<{ breakpoint: number, numOfCopies: number }>` | `undefined` | Responsive configuration for different screen sizes. Note: The numOfCopies value is doubled for each breakpoint |
| `animationDirection` | `"ltr" \| "rtl"` | `"rtl"` | Direction of animation (left-to-right or right-to-left) |
| `className` | `string` | `undefined` | Additional CSS class for styling carousel items |
| `hoverSpeedFactor` | `number` | `1` | Speed multiplier on hover (0 = pause, <1 = slower, >1 = faster) |
| `fade` | `number` | `undefined` | Width in pixels for the fade effect at the edges. Creates a gradient fade at both ends of the carousel |
### Image Carousel Props
Additional props when `itemType="images"`:
| Prop | Type | Description |
| -------------- | ---------- | ---------------------------------------------- |
| `images_links` | `string[]` | Array of image URLs to display in the carousel |
Additional props when `itemType="text"`:
| Prop | Type | Description |
| ------ | -------- | --------------------------------------- |
| `text` | `string` | Text content to display in the carousel |
By default, the carousel automatically adjusts the number of clones based on the viewport width to ensure optimal display and smooth scrolling. This automatic calculation ensures there are no empty spaces in the carousel regardless of screen size.
However, if you need more control over the responsive behavior, you can use the `responsiveClones` prop. This prop accepts an array of breakpoint configurations, where each configuration object has two properties:
- `breakpoint`: The maximum width in pixels for this configuration to apply
- `numOfCopies`: Base number of copies to display at this breakpoint. The actual number of clones will be doubled (e.g., if set to 3, total clones will be 6)
The carousel follows this logic to determine the number of clones:
1. First, it evaluates the `responsiveClones` array from smallest to largest breakpoint.
2. If the current viewport width is greater than all defined breakpoints, it falls back to the `numOfCopies` parameter.
3. If `numOfCopies` is not provided, it uses automatic calculation.
For example:
```tsx
const breakpoints = [
{ breakpoint: 1024, numOfCopies: 3 }, // Applied up to 1024px
{ breakpoint: 1200, numOfCopies: 5 }, // Applied between 1024px and 1200px
];
```
If the viewport width is 1400px (greater than all breakpoints):
- First tries to use `numOfCopies` parameter
- If `numOfCopies` is not provided, falls back to automatic calculation
If neither `responsiveClones` nor `numOfCopies` is provided, the carousel will use its automatic calculation mode to determine the optimal number of copies needed to fill the viewport.
ISC
Azfar Razzaq
Found a bug or have a feature request? Please file an issue at [GitHub Issues](https://github.com/Azfar731/react-infinite-carousel-package/issues).