react-image-turntable

React Image Turntable

Display a set of images as a draggable 360 degree turntable.

Features

• Accessible & screen-reader friendly
• Responsive & intrinsically sized
• Built-in keyboard navigation
• Programmatically controllable
• Teeny Tiny
• Zero dependencies
• Type safe

Install

npm i react-image-turntable
# Or
yarn add react-image-turntable
# Or
pnpm i react-image-turntable

Usage

Example

import { ReactImageTurntable, useReactImageTurntable } from 'react-image-turntable';

const images = [
  'https://via.placeholder.com/1200x800?text=1',
  'https://via.placeholder.com/1200x800?text=2',
  'https://via.placeholder.com/1200x800?text=3',
];

export const App = () => {
  const turntableProps = useReactImageTurntable({ images });

  return <ReactImageTurntable {...turntableProps} />;
};

See the example code for full demo.

useReactImageTurntable Props

Input Props

The useReactImageTurntable hook accepts the following properties.

Props	Type	Required	Default Value	Description
autoRotate.enabled	boolean		false	Whether to automatically rotate the turntable.
autoRotate.interval	number		200	The interval between autorotations in ms.
images	string[]	✓	undefined	List of image src attributes.
initialImageIndex	number		0	Index of image to show first.
movementSensitivity	number		20	The amount a "drag" has to move before an image changes to next or previous.
onIndexChange	(index: number) => void		undefined	Callback to trigger whenever the active index changes.

Output Props

The useReactImageTurntable hook returns the following properties.

Props	Type	Description
activeImageIndex	number	The index of the image currently being shown.
setActiveImageIndex	(index: number) => void	Function to set the active index.
images	string[]	The images passed into the hook.
ref	RefObject<HTMLDivElement>	The ref of the root turntable element.

Note that there is no need for a setImages function. images is not stored in state. If you want to change the images simply change the images prop passed into the hook.

Example Usage

View example

import { ReactImageTurntable, useReactImageTurntable } from 'react-image-turntable';

const images = [
  'https://via.placeholder.com/1200x800?text=1',
  'https://via.placeholder.com/1200x800?text=2',
  'https://via.placeholder.com/1200x800?text=3',
];

export const App = () => {
  const turntableProps = useReactImageTurntable({
    autoRotate: { disabled: true, interval: 75 },
    images,
    initialImageIndex: 1, // Start on the second image.
    movementSensitivity: 50, // Increase the amount of drag needed to change images.
    onIndexChange: (index) => console.log(`Active image index changed to ${index}`),
  });

  const handleSelectFirstImage = () => {
    turntableProps.setActiveIndex(0);
  };

  return (
    <>
      <button type="button" onClick={handleSelectFirstImage}>
        Select first image
      </button>
      <ReactImageTurntable {...turntableProps} />
    </>
  );
};

Custom Styling

The library uses the first image in images[] to intrinsically size the component, it also exports the following classNames allowing you to apply custom styles.

className	Purpose
CLASS_NAME_IMG	Base class for all images.
CLASS_NAME_IMG_PRIMARY	Class of first image in images[] (sets the size of the main component).
CLASS_NAME_IMG_SECONDARY	Class of subsequent images.

---

Contributing

See the contributing guide to get started.

---

Browser Support

The library is built for ES2021.

Notes

• It's recommended you use a minimum of 24-36 for a smooth experience
• Legacy version by @andrewmcoupe