Carousel3D
A perspective-based 3D card carousel that stacks slides in a fan layout — active slide centred and full size, adjacent slides scaled and offset to create depth.
Supports web (CSS transition-driven) and React Native (Reanimated v3-driven) from a single import.
Installation
npm install @cleartrip/ct-design-3d-carousel
# or
pnpm add @cleartrip/ct-design-3d-carousel
Peer dependencies
# Required for all targets
npm install react
# Web only
npm install react-dom
# React Native only
npm install react-native react-native-reanimated react-native-gesture-handler
Follow the official setup guides for Reanimated and GestureHandler:
Note: The native peer dependencies (
react-native,react-native-reanimated,react-native-gesture-handler) are optional. Web-only projects do not need them.
Usage
Basic
import { Carousel3D } from '@cleartrip/ct-design-3d-carousel';
function Example() {
return (
<Carousel3D height="300px" cardWidth="600px">
<img src="/slide1.jpg" alt="Slide 1" />
<img src="/slide2.jpg" alt="Slide 2" />
<img src="/slide3.jpg" alt="Slide 3" />
</Carousel3D>
);
}
With navigation icons
<Carousel3D
height="300px"
cardWidth="600px"
showSliderIcons
onSlide={(index) => console.log('Active slide:', index)}
>
{slides}
</Carousel3D>
With auto-play
<Carousel3D
height="300px"
cardWidth="600px"
autoPlay
autoPlaySpeed={2000}
animationDelay={400}
>
{slides}
</Carousel3D>
With a custom start index
// Start on the third slide (0-indexed)
<Carousel3D height="300px" cardWidth="600px" startIndex={2}>
{slides}
</Carousel3D>
Custom navigation icons
import { MyLeftArrow, MyRightArrow } from './icons';
<Carousel3D
height="300px"
cardWidth="600px"
showSliderIcons
CustomLeftCarousalComponent={<MyLeftArrow />}
CustomRightCarousalComponent={<MyRightArrow />}
>
{slides}
</Carousel3D>
Style overrides (web)
Each styleConfig slot accepts an array of style objects. The styles are
merged with the component's built-in static and dynamic styles via
useWebMergeStyles from @cleartrip/ct-design-style-manager.
<Carousel3D
height="300px"
cardWidth="600px"
styleConfig={{
rootContainer: [{ backgroundColor: '#f5f5f5', padding: 24 }],
sliderCardContainer: [{ borderRadius: 24 }],
}}
>
{slides}
</Carousel3D>
Multiple style objects can be composed in the array — later entries take
precedence (same as React Native's StyleSheet array spreading):
<Carousel3D
styleConfig={{
rootContainer: [baseStyle, conditionalStyle, { marginTop: 16 }],
sliderCardRootContainer: [overrideStyle],
}}
>
{slides}
</Carousel3D>
Style overrides (React Native)
The styleConfig shape is identical on native. Each slot accepts a
Styles[] array and the entries are spread directly onto the View's
style prop.
import { StyleSheet } from 'react-native';
const styles = StyleSheet.create({
card: { borderRadius: 24 },
root: { backgroundColor: '#f5f5f5' },
});
<Carousel3D
height={300}
cardWidth="90%"
styleConfig={{
rootContainer: [styles.root],
sliderCardContainer: [styles.card],
}}
>
{slides}
</Carousel3D>
Props
| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
children | ReactNode[] | — | ✅ | Slides to display. Minimum 2, maximum 5 unique items (internally duplicated when ≤ 5). |
height | string | number | — | No | Fixed height of the carousel frame (e.g. '300px' or 300). |
cardWidth | string | number | '100%' | No | Width of each card. Used to centre the carousel when narrower than the viewport. |
startIndex | number | 0 | No | Index of the initially active slide. |
animationDelay | number | 480 | No | Duration (ms) of each slide transition animation. |
showSliderIcons | boolean | false | No | Show left/right navigation chevron icons on the active slide. |
CustomLeftCarousalComponent | ReactNode | <LeftChevronWithBoundingBox /> | No | Custom element for the left navigation button. |
CustomRightCarousalComponent | ReactNode | <RightChevronWithBoundingBox /> | No | Custom element for the right navigation button. |
autoPlay | boolean | false | No | Enable automatic slide cycling. |
autoPlaySpeed | number | 900 | No | Interval (ms) between auto-play transitions. |
onSlide | (index: number) => void | — | No | Callback fired after each slide change. Receives the new active index. |
styleConfig | I3DCarouselStyleConfig | — | No | Fine-grained style overrides for internal layout slots (see below). |
styleConfig
styleConfig is a single unified interface used by both web and native.
Every slot accepts a Styles[] array — the same pattern as React
Native's style array spreading.
interface I3DCarouselStyleConfig {
rootContainer?: Styles[];
relativeBaseContainer?: Styles[];
sliderRootContainer?: Styles[];
iconsContainer?: Styles[];
leftIconContainer?: Styles[];
rightIconContainer?: Styles[];
sliderCardContainer?: Styles[];
sliderCardRootContainer?: Styles[];
}
Slots
| Slot | Description |
|---|---|
rootContainer | Outermost flex wrapper |
relativeBaseContainer | Relative base that constrains the slide stack |
sliderRootContainer | Absolute container holding all slide wrappers |
iconsContainer | Overlay for left/right navigation icons |
leftIconContainer | Left icon wrapper |
rightIconContainer | Right icon wrapper |
sliderCardContainer | Card content container (shadow, borderRadius) |
sliderCardRootContainer | Per-slide absolute wrapper |
How styles are applied
Web — each Styles[] entry is passed to useWebMergeStyles from
@cleartrip/ct-design-style-manager, which converts raw style objects to
Emotion class names and merges them with the component's built-in class names.
Native — each Styles[] entry is spread directly into the View's
style array alongside the component's makeStyles-generated styles.
Full example
// Web
<Carousel3D
height="300px"
cardWidth="600px"
styleConfig={{
rootContainer: [{ backgroundColor: '#f0f4ff' }],
relativeBaseContainer: [{ borderRadius: 16 }],
sliderCardContainer: [{ borderRadius: 24, boxShadow: '0 8px 32px rgba(0,0,0,0.12)' }],
sliderCardRootContainer: [{ overflow: 'hidden' }],
}}
>
{slides}
</Carousel3D>
// React Native
import { StyleSheet } from 'react-native';
const s = StyleSheet.create({
root: { backgroundColor: '#f0f4ff' },
card: { borderRadius: 24 },
});
<Carousel3D
height={300}
cardWidth="90%"
styleConfig={{
rootContainer: [s.root],
sliderCardContainer: [s.card],
}}
>
{slides}
</Carousel3D>
Animation Details
Web
Animation is driven entirely by CSS transition on transform and opacity. When slideCurrent changes, React re-renders each CarouselSlide with new target transform values. The browser interpolates between states using the declared cubic-bezier(0.3, 0.46, 0.36, 0.93) easing and the animationDelay duration.
No @keyframes, no JS animation loop, no requestAnimationFrame. Smooth, composited, GPU-accelerated.
The 5-position layout:
| Position | translateX | scale |
|---|---|---|
| Active | 0% | 1.0 |
| Pre-active (left-1) | -18% | 0.75 |
| Pro-active (right-1) | +18% | 0.75 |
| Pre-pre-active (left-2) | -34% | 0.5 |
| Pro-pro-active (right-2) | +34% | 0.5 |
| Hidden | 0% | 0.0 |
React Native
Animation is driven by Reanimated v3 — useSharedValue, withTiming, useAnimatedStyle. All animations run on the UI thread with no JS bridge round-trips.
Each slide owns five shared values (zIndex, translateX, translateY, scale, opacity). When slideCurrent changes, a useEffect fires and drives each value to its new target with withTiming(target, { duration: animationDelay, easing: Easing.inOut(Easing.ease) }).
Swipe gestures are handled by PanGestureHandler from react-native-gesture-handler. The gesture worklet bridges to React state via runOnJS.
Accessibility
- Left/right navigation icons are wrapped in
<Pressable>(native) or<Container role="button">(web) with appropriatearia-label/accessibilityLabel. - Touch target for navigation icons: ensure icons are at least 44×44 pt.
- Slide content should include
altattributes on images and appropriate ARIA for other content. - The component does not auto-announce slide changes to screen readers. Consider adding a visually hidden live region if your use case requires it.
Styling Architecture
Styles follow the design-system migration rules:
- Static styles (never change) — defined at module level with
makeStylesfrom@cleartrip/ct-design-style-manager. Processed through the design-system theme and emitted as Emotion class names (web) or style objects (native) at import time. - Dynamic styles (depend on props) — computed inside the component with
useStyles. Re-run only when deps change. - Combined output (web) — merged into a single
classNamestring viauseWebMergeStyles, passed toContainer. - Combined output (native) — merged into a
stylearray and spread ontoView. - No
@emotion/styledwrappers — all styled components have been removed. - No SCSS/CSS files — the previous
index.scss(class-based animation) has been replaced by computed CSS viamakeStyles.
Migration from yagami/core/components
- import Carousel3D from 'yagami/core/components/components/3DCarousel';
+ import { Carousel3D } from '@cleartrip/ct-design-3d-carousel';
- import Carousel3D from 'yagami/core/components/components/3DCarousel/index.native';
+ import { Carousel3D } from '@cleartrip/ct-design-3d-carousel';
// Metro resolves .native.ts automatically
Breaking changes
| Area | Before (yagami) | After (ct-design-system) |
|---|---|---|
styleConfig shape | rootContainerStyles?: Styles[] (native) / rootContainerProps?: { css?, className? } (web) | rootContainer?: Styles[] — unified, same on both platforms |
| Key naming | rootContainerProps (web) / rootContainerStyles (native) | rootContainer — no Props / Styles suffix |
| SCSS import | import './index.scss' not required externally | No CSS file to import — styles are bundled |
| Swipe (native) | useSwipeable (internal Yagami hook) | PanGestureHandler (gesture-handler) |
| Animation (native) | Reanimated v3 ✅ (same) | Reanimated v3 ✅ |
Changelog
2.21.0
- Migrated from
yagami/core/components/components/3DCarousel - Unified
styleConfig— singleI3DCarouselStyleConfiginterface used on both web and native; all slot keys acceptStyles[]arrays (e.g.rootContainer: [style1, style2]) - Removed separate
I3DCarouselNativeStyleConfigandIWebContainerStylePropsinterfaces - Removed
StyleSheet.createfrom native files; replaced withmakeStylesfrom@cleartrip/ct-design-style-manager - Replaced
@emotion/styledwrappers withmakeStyles+useStyles+useWebMergeStyles - Removed
index.scss(class-based CSS animations); replaced with CSStransitioncomputed viamakeStyles - Added full React Native implementation (
Corousel3D.native.tsx+CarouselSlide.native.tsx) replacing the previous stub - Updated animation for native: Reanimated v3 throughout (
useSharedValue,withTiming,useAnimatedStyle) - Updated swipe for native:
PanGestureHandlerfromreact-native-gesture-handler - Added
react-native-reanimated+react-native-gesture-handleras optional peer dependencies - Normalised constants: unified
CAROUSEL_CARD_CLASSNAMESbetween web and native