react-native-3d-model-carousel

A React Native library for rendering interactive 3D .glb/.gltf models in a simple carousel with previous/next controls and optional swipe navigation.

Preview

Installation

npm install react-native-3d-model-carousel @react-three/fiber @react-three/drei three

If you use Expo, also install expo-gl.

Usage

import { ModelCarousel } from 'react-native-3d-model-carousel';
import { Pressable, Text } from 'react-native';

import Car1 from './assets/Car1.glb';
import Car2 from './assets/Car2.glb';
import Car3 from './assets/Car3.glb';

export default function App() {
  return (
    <ModelCarousel
      models={[
        {
          path: Car1,
          scale: 1.1,
          position: [0, -3, 0],
          cameraPosition: [0, 7, 6],
        },
        {
          path: Car2,
          scale: 1.5,
          position: [0, -2.4, 0],
          cameraPosition: [0, 6, 5],
        },
        Car3,
      ]}
      width="100%"
      height="100%"
      scale={1.3}
      position={[0, -3, 0]}
      cameraPosition={[0, 8, 6]}
      fov={40}
      autoRotate
      autoRotateSpeed={5}
      autoPlay
      autoPlayInterval={3000}
      containerStyle={{ backgroundColor: '#f0f0f0' }}
      renderPrevButton={({ onPress, disabled }) => (
        <Pressable onPress={onPress} disabled={disabled}>
          <Text>Prev</Text>
        </Pressable>
      )}
      renderNextButton={({ onPress, disabled }) => (
        <Pressable onPress={onPress} disabled={disabled}>
          <Text>Next</Text>
        </Pressable>
      )}
    />
  );
}

TypeScript asset declarations

If your app does not already declare 3D asset modules, add this to a *.d.ts file:

declare module '*.glb' {
  const content: any;
  export default content;
}

declare module '*.gltf' {
  const content: any;
  export default content;
}

Props

| Prop | Type | Default | Description | | ------------------ | ---------------------- | -------------- | -------------------------------------------------- | | models | ModelCarouselItem[] | - | Array of model assets or per-model config objects. | | width | DimensionValue | '100%' | Carousel container width. | | height | DimensionValue | '100%' | Carousel container height. | | containerStyle | StyleProp<ViewStyle> | undefined | Additional wrapper style. | | scale | number | 0.8 | Model scale. | | position | number[] | [0, -2.7, 0] | Model XYZ position. | | cameraPosition | number[] | [0, 9, 5] | Camera XYZ position. | | fov | number | 35 | Camera field of view. | | autoRotate | boolean | true | Enables model auto-rotation. | | autoRotateSpeed | number | 10 | Auto-rotation speed. | | autoPlay | boolean | false | Automatically advances to the next model in an infinite loop. | | autoPlayInterval | number | 2500 | Delay in milliseconds between each automatic model change. | | enableSwipeNavigation | boolean | true | Enables horizontal swipe to switch models and disables model panning. | | swipeThreshold | number | 36 | Minimum horizontal drag distance (px) required to trigger swipe navigation. | | showPaginationDots | boolean | true | Shows bottom dots indicating total models and current active model. | | showDefaultButtons | boolean | false | Shows built-in previous/next buttons when custom buttons are not provided. | | renderPrevButton | (props) => ReactNode | undefined | Custom previous button renderer. | | renderNextButton | (props) => ReactNode | undefined | Custom next button renderer. |

ModelCarouselItem can be either:

type ModelCarouselItem =
  | unknown
  | {
      path: unknown;
      scale?: number;
      position?: number[];
      cameraPosition?: number[];
    };

When a model item includes scale, position, or cameraPosition, those values override the global props for that specific model only.

renderPrevButton and renderNextButton receive:

type NavigationButtonRenderProps = {
  onPress: () => void;
  disabled: boolean;
  index: number;
  total: number;
  isAnimating: boolean;
};

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library