React Swipeable Views Utilities

Common errors

• Error: `SwipeableViews` does not support `componentWillReceiveProps` or `componentWillMount` on React 16.3+.

  cause Using `react-swipeable-views-utils` versions `>=0.14.0-alpha.0` with React < 16.3, or an older `react-swipeable-views` with a newer React.
  fix Ensure both `react` and `react-swipeable-views` are at `^16.3.0` or higher, and `react-swipeable-views-utils` is at `0.14.0` or later.

• TypeError: Cannot read properties of undefined (reading 'scrollTo')

  cause This error can occur if `scrollTop` is not handled correctly in some environments, or if a view portal is used incorrectly, preventing proper DOM manipulation.
  fix Upgrade to `0.14.0` or later, which includes fixes for `scrollTop` and issues with portals inside views. Ensure your `SwipeableViews` component is rendered in a standard DOM flow.

• Warning: Accessing PropTypes via the main 'react' package is deprecated. Use the 'prop-types' package instead.

  cause Older versions of `react-swipeable-views` or its utilities might still rely on `React.PropTypes` directly.
  fix Ensure `react-swipeable-views` and `react-swipeable-views-utils` are on their latest versions (`0.14.x`) which should address `prop-types` usage correctly.

Warnings

• breaking The package removed legacy context, which might affect applications relying on older React context APIs. Ensure your `react-swipeable-views` setup does not use deprecated context features.
  Fix: Update `react-swipeable-views` and refactor any legacy context usage to React's new Context API or ensure HOCs are correctly composed.
• breaking Version `0.14.0-alpha.0` introduced a minimum React version requirement of `16.3` due to its use of `UNSAFE_*` lifecycle methods (`componentWillReceiveProps`, `componentWillMount`) to workaround console warnings. Using older React versions will lead to errors or warnings.
  Fix: Upgrade your project's React dependency to `^16.3.0` or higher to ensure compatibility.
• gotcha When using the `autoPlay` HOC, the `onChangeIndex` prop's third parameter was previously swallowed in certain cases. This was fixed, but ensure your `onChangeIndex` callback correctly handles its arguments if you experienced unexpected behavior.
  Fix: Upgrade to `0.14.0` or later to ensure the `onChangeIndex` callback receives all expected parameters.
• gotcha For mouse events to work with `react-swipeable-views` (and thus with these utilities), you might need to explicitly add the `enableMouseEvents` prop to your `SwipeableViews` component. This is not always intuitive for users expecting touch and mouse parity.
  Fix: Add `enableMouseEvents` prop to your `SwipeableViews` component: `<SwipeableViews enableMouseEvents={true} />`.
• gotcha The `autoplay` HOC pauses when the window is hidden. While this is often desired to save resources, it can be a 'gotcha' if you expect continuous autoplay even when the tab is in the background.
  Fix: No direct fix if you require background autoplay, as this is intended behavior. Consider implementing custom interval logic if this is a critical requirement.

Install

• npm install react-swipeable-views-utils npm
• yarn add react-swipeable-views-utils yarn
• pnpm add react-swipeable-views-utils pnpm

Imports

• autoPlay
  wrong:

  const autoPlay = require('react-swipeable-views-utils').autoPlay;

  correct:

  import { autoPlay } from 'react-swipeable-views-utils';

  HOC for adding automatic slide progression. Typically used to wrap `SwipeableViews`.
• virtualize
  wrong:

  import virtualize from 'react-swipeable-views-utils/lib/virtualize';

  correct:

  import { virtualize } from 'react-swipeable-views-utils';

  HOC for rendering only visible slides, improving performance for large numbers of views. Requires a `slideRenderer` prop.
• bindKeyboard
  wrong:

  import { BindKeyboard } from 'react-swipeable-views-utils';

  correct:

  import { bindKeyboard } from 'react-swipeable-views-utils';

  HOC to enable keyboard left/right arrow navigation. Ensure the wrapped component is focusable or a suitable element is given focus.

Quickstart

This quickstart demonstrates how to use the `autoPlay` HOC with `react-swipeable-views` to create a self-advancing carousel, including basic navigation dots.

import * as React from 'react';
import SwipeableViews from 'react-swipeable-views';
import { autoPlay } from 'react-swipeable-views-utils';

const AutoPlaySwipeableViews = autoPlay(SwipeableViews);

const DemoCarousel = () => {
  const [index, setIndex] = React.useState(0);

  const handleChangeIndex = (idx) => {
    setIndex(idx);
  };

  return (
    <div style={{ maxWidth: 400, margin: 'auto' }}>
      <h2>Auto-Playing Carousel</h2>
      <AutoPlaySwipeableViews
        index={index}
        onChangeIndex={handleChangeIndex}
        enableMouseEvents
        interval={3000}
      >
        <div style={{ background: '#f44336', height: 200, display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
          <h3>Slide 1</h3>
        </div>
        <div style={{ background: '#2196f3', height: 200, display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
          <h3>Slide 2</h3>
        </div>
        <div style={{ background: '#4caf50', height: 200, display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
          <h3>Slide 3</h3>
        </div>
      </AutoPlaySwipeableViews>
      <div style={{ textAlign: 'center', marginTop: 10 }}>
        {['●', '●', '●'].map((dot, i) => (
          <span
            key={i}
            style={{
              cursor: 'pointer',
              margin: '0 5px',
              color: i === index ? '#333' : '#bbb',
              fontSize: '24px'
            }}
            onClick={() => setIndex(i)}
          >
            {dot}
          </span>
        ))}
      </div>
    </div>
  );
};

export default DemoCarousel;