react-carousel-query

| Statements | Branches | Functions | Lines | | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | | | | |

• Lightweight React component with minimal footprint
• Infinite carousel with automatic pagination management
• Fetches data on demand as users navigate through slides
• Zero external dependencies (only React and classnames)
• Fully customizable slide, arrow, and badge rendering
• Optimized for performance
• Touch and mouse swipe support for mobile and desktop
• TypeScript declarations included

Working demo here

Installation

Requirements: React 16.8.0 or higher

npm install react-carousel-query

Props

| Prop | Type | Default | Description | | ------------- | ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- | | renderItem | function | required | Render function for each slide. Receives { item } as argument. You can render just an img or any other React element. | | getData | function | required | Async function to fetch items. Receives { offset, cursor, limit } and must return { total, items }. Each item must have an id property (string or number). | | fetchStep | number | 3 | Number of items requested per fetch call. Data is fetched preemptively as the user navigates, ensuring smooth transitions. | | hideIndex | boolean | false | Hide the index badge in the top right corner. | | showArrows | boolean | false | Show navigation arrows. Also enabled when renderArrow is provided. | | renderArrow | function | undefined | Custom render function for arrows. | | renderBadge | function | undefined | Custom render function for the index badge. |

Usage

Basic Example (Offset-based pagination)

import ReactCarouselQuery from 'react-carousel-query'
import 'react-carousel-query/styles.css' // Required for styles

const getData = async ({ offset, limit }) => {
  const response = await fetch(`https://api.example.com/items?offset=${offset}&limit=${limit}`)
  const { data } = await response.json()
  return {
    total: data.total, // Total number of items available
    items: data, // Each item must have an `id` property (string | number)
  }
}

const App = () => (
  <ReactCarouselQuery
    renderItem={({ item }) => <img src={item.imgSrc} alt={item.name} />}
    getData={getData}
  />
)

Cursor-based pagination

To use cursor-based pagination, return nextCursor in your response. The component auto-detects the pagination mode:

const getData = async ({ cursor, limit }) => {
  const url = cursor
    ? `https://api.example.com/items?cursor=${cursor}&limit=${limit}`
    : `https://api.example.com/items?limit=${limit}`

  const response = await fetch(url)
  const { data, nextCursor, totalCount } = await response.json()

  return {
    items: data,
    nextCursor, // null when there are no more pages
    total: totalCount, // optional - will be inferred from items if not provided
  }
}

For a complete working example, check out our demo code.

Setup

npm install

How to run

npm run dev

How to build

npm run build

How to test

npm test

Contributions

Contributions are welcome. Just open a PR and feel free to contact me :-).

You can also start looking into ope issues, specially the ones with good first issue label.

Documentation

Run Storybook for interactive documentation:

npm run storybook