Convex Carousel
A high-performance, physics-based infinite carousel. Items mathematically scale based on an inverted parabola, creating a 3D "convex" lens bulging visual effect using strictly 2D DOM manipulation for maximum FPS.
Last Modified:Aug 17, 2026
Install
CLI
convex-carousel
Or install a specific demo variant:
convex-carousel-demo
Manual
1. Install Dependencies
Dependencies
2. Add Source Code
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | ConvexCarouselItem[] | Required | Array of image objects to display. Automatically duplicated to ensure an infinite loop. |
visibleItems | number | 7 | Mobile-first default for visible items. |
maxHeight | number | 450 | Mobile-first default for the center item's max height in pixels. |
minHeight | number | 120 | Mobile-first default for the outer items' min height in pixels. |
breakpoints | Record<number, CarouselBreakpoint> | undefined | Tailwind-style min-width breakpoints for responsive sizing. e.g., { 640: { visibleItems: 5 } } |
autoMove | boolean | false | Whether the carousel should move automatically. |
autoMoveType | "continuous" | "step" | "continuous" | The type of auto-movement. |
autoMoveSpeed | number | 0.01 | The velocity of the continuous auto-scroll. |
stepInterval | number | 3000 | The delay (in ms) between steps if autoMoveType is "step". |
stepDuration | number | 1 | The duration (in seconds) of the snapping animation. |
scrollMultiplier | number | 0.005 | How aggressively the carousel responds to drag velocity. |
friction | number | 0.95 | The physics friction applied to drag momentum. |