react-native-pure-carousel

Pure JavaScript image carousel for React Native and Expo with an animated pagination indicator and a full-screen, zoomable modal viewer. No native code of its own, so it runs in Expo Go, on web, and on the New Architecture.

Installation

yarn add react-native-pure-carousel react-native-safe-area-context

or

npm install react-native-pure-carousel react-native-safe-area-context

react-native-safe-area-context is a peer dependency used by the full-screen viewer to keep the close button clear of the status bar. Expo projects can install it with npx expo install react-native-safe-area-context.

Requirements: React 19+, React Native 0.78+ (Expo SDK 53+).

Usage

import PureCarousel from 'react-native-pure-carousel';

const images = [1070, 1059, 1025].map((id) => ({
  source: { uri: `https://picsum.photos/id/${id}/720/480` },
  // Optional higher resolution image for the full-screen viewer
  originalSource: { uri: `https://picsum.photos/id/${id}/1280/720` },
}));

export default function Gallery() {
  return <PureCarousel images={images} height={240} />;
}

Pressing an image opens the full-screen viewer. Closing the viewer scrolls the carousel to the image that was being viewed.

Controlling the carousel

import { useRef } from 'react';
import PureCarousel, { type PureCarouselRef } from 'react-native-pure-carousel';

function Gallery() {
  const ref = useRef<PureCarouselRef>(null);

  return (
    <>
      <PureCarousel ref={ref} images={images} onChangeIndex={console.log} />
      <Button title="Next" onPress={() => ref.current?.goNext()} />
    </>
  );
}

Props

All View props are accepted in addition to the following.

| Prop | Type | Default | Description | | ------------------ | --------------------------------------- | ------------ | ----------------------------------------------------------------- | | images | PureImageProps[] | required | Image props per slide plus an optional originalSource. | | width | number | window width | Width of one slide. | | height | number | 260 | Height of the carousel. | | initialIndex | number | 0 | Slide shown first. | | imageConfigs | Partial<PureImageProps> | | Props applied to every image, overridden by per-image props. | | preferOriginal | boolean | false | Render originalSource in the carousel itself when available. | | showPagination | boolean | true | Show the pagination indicator below the slides. | | paginationProps | Partial<PaginationProps> | | Customise the built-in indicator (see below). | | renderPagination | (props: PaginationProps) => ReactNode | | Render your own indicator. | | disableModal | boolean | false | Do not open the full-screen viewer on press. | | onImagePress | (index: number) => void | | Called when a slide is pressed. | | onChangeIndex | (index: number) => void | | Called when the active slide changes. | | ref | Ref<PureCarouselRef> | | Exposes goNext(), goPrev() and goToIndex(index, animated?). |

Pagination props

| Prop | Type | Default | | --------------------------- | -------------------- | ----------- | | mode | 'line' \| 'circle' | 'line' | | circleSize | number | 8 | | lineWidth | number | full width | | lineHeight | number | 2 | | gutterSize | number | 4 | | itemBackgroundColor | string | '#e2e8f0' | | itemActiveBackgroundColor | string | '#334155' |

Pagination is also exported on its own for use with custom lists. It needs horizontalAnimatedScrollPosition (an Animated.Value driven by the list's horizontal scroll offset), itemsCount and containerWidth.

Other exports

• PureCarouselBase: the carousel without the modal viewer.
• PureModalViewer: the full-screen viewer, controlled through a ref with openModal(index) and closeModal().
• Types: PureCarouselProps, PureCarouselRef, PureImageProps, PaginationProps, PaginationMode, PureModalViewerRef.

Contributing

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

License

MIT