React Images

A mobile-friendly, highly customizable, carousel component for displaying media in ReactJS. Images courtesy of Unsplash.

Getting Started

Start by installing react-images

yarn add react-images

Using the Carousel

Import the carousel from react-images at the top of a component and then use it in the render function.

import React from 'react';
import Carousel from 'react-images';

const images = [{ source: 'path/to/image-1.jpg' }, { source: 'path/to/image-2.jpg' }];

class Component extends React.Component {
  render() {
    return <Carousel views={images} />;
  }
}

Using the Modal

Import the modal and optionally the modal gateway from react-images at the top of a component and then use it in the render function.

The ModalGateway will insert the modal just before the end of your <body /> tag.

import React from 'react';
import Carousel, { Modal, ModalGateway } from 'react-images';

const images = [{ src: 'path/to/image-1.jpg' }, { src: 'path/to/image-2.jpg' }];

class Component extends React.Component {
  state = { modalIsOpen: false }
  toggleModal = () => {
    this.setState(state => ({ modalIsOpen: !state.modalIsOpen }));
  }
  render() {
    const { modalIsOpen } = this.state;

    return (
      <ModalGateway>
        {modalIsOpen ? (
          <Modal onClose={this.toggleModal}>
            <Carousel views={images} />
          </Modal>
        ) : null}
      </ModalGateway>
    );
  }
}

Example Gallery

Source

Below is a pretty typical implementation; the index of the selected thumbnail is passed to the currentIndex property of the carousel. All of the components, styles, getters, animations and functionality are the defaults provided by the library.

Carousel Props

`componentsObject<ComponentType>`

Replace any or all of the carousel components with your own to create the layout and functionality you desire. Detailed documentation on the Components page.

// FrameProps, ModalProps, StyleFn, TrackProps, and ViewType declared below

type CommonProps = {
  carouselProps: Object,
  currentIndex: number,
  currentView: ViewType,
  frameProps FrameProps,
  getStyles: StyleFn,
  innerProps: Object,
  isFullscreen: boolean,
  isModal: boolean,
  modalProps: ModalProps,
  interactionIsIdle: boolean,
  trackProps: TrackProps,
  views: Array<ViewType>,
}

type components = {
  Container: ComponentType<CommonProps>,
  Footer: ComponentType<CommonProps>,
  FooterCaption: ComponentType<CommonProps>,
  FooterCount: ComponentType<CommonProps>,
  Header: ComponentType<CommonProps>,
  HeaderClose: ComponentType<CommonProps>,
  HeaderFullscreen: ComponentType<CommonProps>,
  Navigation: ComponentType<CommonProps>,
  NavigationPrev: ComponentType<CommonProps>,
  NavigationNext: ComponentType<CommonProps>,
  View: ComponentType<CommonProps>,
}

`currentIndexNumber = 0`

React-Images manages the index state internally. This property is exposed so you can take control of it, or initiate the carousel from a certain point.

`framePropsObject`

Passed on to react-view-pager's Frame component. Check out #frame-props for more information.

{
  accessibility: boolean,
  autoSize: true | false | 'width' | 'height',
  springConfig: { [key: string]: number },
  tag: string,
}

`formattersObject<Function>`

Formatters get called with common props to render labels and titles for certain components. Replace the default formatters if you want to tweak the text or change the language.

// CommonProps declared above in the `component` prop type

{
  getAltText: (CommonProps) => string, // {caption} | Image {currentIndex}
  getNextLabel: (CommonProps) => string, // Show slide {nextIndex} of {totalCount}
  getPrevLabel: (CommonProps) => string, // Show slide {prevIndex} of {totalCount}
  getNextTitle: (CommonProps) => string, // Next (right arrow)
  getPrevTitle: (CommonProps) => string, // Previous (left arrow)
  getCloseLabel: (CommonProps) => string, // Close (esc)
  getFullscreenLabel: (CommonProps) => string, // [Enter | Exit] fullscreen (f)
}

`hideControlsWhenIdleNumber | false = 3000`

The duration, in milliseconds, to wait before hiding controls when the user is idle.

`modalPropsObject`

Available when the Carousel is within a Modal. The applicable props are cloned and passed on for use inside Carousel components.

{
  allowFullscreen: boolean,
  isFullscreen: boolean,
  onClose: (SyntheticEvent) => void,
  preventScroll: boolean,
  toggleFullscreen: () => void,
}

`showNavigationOnTouchDeviceboolean = false`

Whether image carousel navigation buttons should be hidden or shown on touch-enabled devices. (Default: hidden)

`stylesObject<Function>`

React-Images ships each Carousel component with default styles. You can extend or replace these using the styles property.

type StyleObj = { [key: string]: any }
type State = {
  isFullscreen: boolean,
  isModal: boolean,
  interactionIsIdle: boolean,
}

type StyleFn = (StyleObj, State) => StyleObj

{
  container: StyleFn,
  footer: StyleFn,
  footerCaption: StyleFn,
  footerCount: StyleFn,
  header: StyleFn,
  headerClose: StyleFn,
  headerFullscreen: StyleFn,
  navigation: StyleFn,
  navigationPrev: StyleFn,
  navigationNext: StyleFn,
  view: StyleFn,
}

`trackPropsObject = { swipe: 'touch' }`

Passed on to react-view-pager's Track component. Check out #track-props for more information.

{
  align: number,
  animations: Array<{ props: string, stops: Array<[number, number]> }>,
  axis: 'x' | 'y',
  contain: boolean,
  currentView: any,
  flickTimeout: number,
  infinite: boolean,
  instant: boolean,
  onRest: () => void,
  onScroll: () => void,
  onSwipeEnd: () => void,
  onSwipeMove: () => void,
  onSwipeStart: () => void,
  onViewChange: number => void,
  springConfig: { [key: string]: number },
  swipe: true | false | 'mouse' | 'touch',
  swipeThreshold: number,
  tag: any,
  viewsToMove: number,
  viewsToShow: number | 'auto',
}

`viewsArray<Object> required`

The data shape for each view in your carousel. This must be an array of objects, though the key/value pairs in the objects can be whatever you want.

When using "non-standard" view data you must provide a View component that can interpret and render it.

// the default View component expects

Array<{
  caption?: string | Node,
  source: string | {
    download?: string,
    fullscreen?: string,
    regular: string,
    thumbnail?: string,
  },
}>

Modal Props

`allowFullscreenBoolean = true`

Whether the user should be allowed to fullscreen the dialog, either by clicking the Fullscreen button or from an `F` keypress.

`childrenCarouselType required`

Modal expects a single Carousel child. It will not behave as expected otherwise.

`closeOnBackdropClickBoolean = true`

Whether the `onClose` function should be called when the backdrop is clicked.

`closeOnEscBoolean = true`

Whether the `onClose` function should be called when the `esc` key is pressed

`onCloseFunction required`

Function called to request close of the modal

(Event) => void

`stylesObject<Function>`

React-Images ships each Modal component with default styles. You can extend or replace these using the styles property.

type StyleObj = { [key: string]: any }
type State = { isFullscreen: boolean }

type StyleFn = (StyleObj, State) => StyleObj

{
  blanket: StyleFn,
  dialog: StyleFn,
  positioner: StyleFn,
}

`preventScrollBoolean = true`

Determines whether scrolling is prevented via react-scrolllock.