@widergy/mobile-ui 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.3.0](https://github.com/widergy/mobile-ui/compare/v2.2.0...v2.3.0) (2025-12-01)
+
+
+### Features
+
+* [UGGC-23] carousel autoplay ([#464](https://github.com/widergy/mobile-ui/issues/464)) ([5a81315](https://github.com/widergy/mobile-ui/commit/5a81315a79571e3b833e99b6a96f40ecf4684571))
+
 # [2.2.0](https://github.com/widergy/mobile-ui/compare/v2.1.4...v2.2.0) (2025-11-28)
 
 

package/lib/components/Carousel/README.md

@@ -11,6 +11,8 @@ For example, if `contentHeight` and `contentWidth` are not set, the carousel wil
 
 | NAME                                                                                   | TYPE            | REQUIRED | DESCRIPTION                                                                                                                                                 | DEFAULT                                     |
 | ---                                                                                    | ---             | ---      | ---                                                                                                                                                         | ---                                         |
+| autoPlay                                                                               | bool            | No       | Whether the carousel should automatically scroll to the next item.                                                                                          | * `false`                                   |
+| autoPlayDelay                                                                          | number          | No       | The delay between each auto scroll.                                                                                                                         | * `3000`                                    |
 | ...[ScrollView props]('https://facebook.github.io/react-native/docs/scrollview#props') | ScrollViewProps | No       | Excluded `alwaysBounceHorizontal`, `alwaysBounceVertical`, `automaticallyAdjustContentInsets`, `pagingEnabled`, `scrollEventThrottle` & `scrollsToTop`.     | `ScrollView.defaultProps`                   |
 | horizontal                                                                             | bool            | No*      | The orientation of the carousel.                                                                                                                            | * `true`                                    |
 | contentHeight                                                                          | number          | No*      | The `height` of each carousel item. Also the height of the carousel itself, if the prop `horizontal` is `true`.                                             | * `0`                                       |

package/lib/components/Carousel/components/CarouselComponent/index.js

@@ -6,23 +6,30 @@ import styles from '../../styles';
 import propTypes, { carouselForcedProps } from '../../propTypes';
 import { checkSizeProp, CAROUSEL_MOUNT_DELAY, EXTRA_CAROUSEL_ITEMS } from '../../constants';
 
+import { validateIndex } from './utils';
+
 class CarouselComponent extends Component {
   constructor(props) {
     super(props);
     this.ref = createRef();
-    const { initialIndex: currentIndex, spacing, visibleEdge } = props;
+    const { initialIndex, spacing, visibleEdge } = props;
     checkSizeProp(spacing, 'spacing');
     checkSizeProp(visibleEdge, 'visibleEdge');
     this.state = {
-      currentIndex,
+      autoPlayTimeout: null,
+      autoScrollRestartTimeout: null,
+      currentIndex: validateIndex(initialIndex, 0),
+      isAutoScrolling: false,
       opacity: 0,
       opacityTimeout: null,
+      resumeAutoPlayTimeout: null,
       timeout: null
     };
   }
 
   componentDidMount() {
-    const { initialIndex } = this.props;
+    const { initialIndex, autoPlay } = this.props;
+    const validInitialIndex = validateIndex(initialIndex, 0);
     /**
      * These timeouts are required to scroll to the initial index on mount.
      * They are assigned to state variables because state is asynchronous.
@@ -30,23 +37,29 @@ class CarouselComponent extends Component {
      * We can then cancel the timeouts in case the component unmounts before they were called.
      */
     const timeout = setTimeout(() => {
-      this.scrollToIndex(initialIndex);
+      this.scrollToIndex(validInitialIndex);
+      if (autoPlay) {
+        this.startAutoPlay();
+      }
     }, CAROUSEL_MOUNT_DELAY);
+
     const opacityTimeout = setTimeout(() => this.setState({ opacity: 1 }), CAROUSEL_MOUNT_DELAY + 10);
-    this.setState({
-      opacityTimeout,
-      timeout
-    });
+
+    this.setState({ opacityTimeout, timeout });
   }
 
   componentWillUnmount() {
-    const { opacityTimeout, timeout } = this.state;
+    const { opacityTimeout, timeout, autoPlayTimeout, resumeAutoPlayTimeout, autoScrollRestartTimeout } =
+      this.state;
     /**
      * Here we cancel the timeouts in case they were not executed before the component was unmounted.
      * This avoids memory leaks (because if we don't do it, it will set state to an unmounted component).
      */
     clearTimeout(opacityTimeout);
     clearTimeout(timeout);
+    clearTimeout(autoPlayTimeout);
+    clearTimeout(resumeAutoPlayTimeout);
+    clearTimeout(autoScrollRestartTimeout);
   }
 
   changeCurrentIndex = index => {
@@ -58,36 +71,145 @@ class CarouselComponent extends Component {
 
   changeInternalIndex = index => {
     const { currentIndex } = this.state;
-    if (index !== currentIndex) {
-      this.setState({ currentIndex: index }, () => this.changeCurrentIndex(index));
+    const { items, loop } = this.props;
+    const validIndex = validateIndex(index, currentIndex);
+
+    if (validIndex !== currentIndex) {
+      this.setState({ currentIndex: validIndex }, () => {
+        let indexToReport = validIndex;
+        if (loop) {
+          indexToReport = ((validIndex % items.length) + items.length) % items.length;
+        }
+        this.changeCurrentIndex(indexToReport);
+      });
     }
   };
 
+  startAutoPlay = () => {
+    const { autoPlay, autoPlayDelay, items } = this.props;
+    if (!autoPlay || items.length <= 1) return;
+
+    this.clearAutoPlay();
+    const autoPlayTimeout = setTimeout(this.autoPlayNext, autoPlayDelay);
+    this.setState({ autoPlayTimeout });
+  };
+
+  clearAutoPlay = () => {
+    const { autoPlayTimeout } = this.state;
+    if (autoPlayTimeout) {
+      clearTimeout(autoPlayTimeout);
+      this.setState({ autoPlayTimeout: null });
+    }
+  };
+
+  autoPlayNext = () => {
+    const { currentIndex } = this.state;
+    const { items, loop } = this.props;
+
+    if (!items || items.length <= 1) return;
+
+    const nextIndex = loop
+      ? (currentIndex + 1) % items.length
+      : currentIndex + 1 >= items.length
+        ? 0
+        : currentIndex + 1;
+
+    this.setState({ isAutoScrolling: true });
+    this.scrollToIndex(nextIndex, true, false, true);
+  };
+
+  pauseAutoPlay = () => {
+    const { autoPlay } = this.props;
+    if (autoPlay) {
+      this.clearAutoPlay();
+      const { resumeAutoPlayTimeout } = this.state;
+      if (resumeAutoPlayTimeout) {
+        clearTimeout(resumeAutoPlayTimeout);
+        this.setState({ resumeAutoPlayTimeout: null });
+      }
+    }
+  };
+
+  resumeAutoPlay = (delay = 1000) => {
+    const { autoPlay } = this.props;
+    if (autoPlay) {
+      const { resumeAutoPlayTimeout } = this.state;
+      if (resumeAutoPlayTimeout) {
+        clearTimeout(resumeAutoPlayTimeout);
+      }
+
+      const newResumeTimeout = setTimeout(() => {
+        this.startAutoPlay();
+        this.setState({ resumeAutoPlayTimeout: null });
+      }, delay);
+
+      this.setState({ resumeAutoPlayTimeout: newResumeTimeout });
+    }
+  };
+
+  handleTouchStart = () => this.pauseAutoPlay();
+
+  handleTouchEnd = () => this.resumeAutoPlay();
+
   handleScroll = ({ nativeEvent: { contentOffset } }) => {
     const { horizontal, contentHeight, contentWidth, items, loop, spacing, visibleEdge } = this.props;
+    const { isAutoScrolling } = this.state;
     const offset = horizontal ? contentOffset.x : contentOffset.y;
     const size = (horizontal ? contentWidth : contentHeight) - visibleEdge * 2 - spacing;
     const index = Math.round(offset / size);
     const last = items.length - 1;
-    const boundary = spacing + visibleEdge;
-    const isLast = index <= 1 && offset <= size + boundary;
-    const isFirst = index >= last + 3 && offset >= (last + 3) * size - boundary;
+    const isLast = index <= 1;
+    const isFirst = index >= last + 3;
+
+    if (!isAutoScrolling) {
+      this.pauseAutoPlay();
+      this.resumeAutoPlay(1500);
+    }
+
     if (loop) {
-      if (isLast) this.scrollToIndex(last);
-      else if (isFirst) this.scrollToIndex(0);
-      else this.changeInternalIndex(index - EXTRA_CAROUSEL_ITEMS);
-    } else this.changeInternalIndex(index);
+      if (isLast) {
+        this.scrollToIndex(last, false, false, true);
+        this.setState({ currentIndex: last }, () => {
+          this.changeCurrentIndex(last);
+        });
+      } else if (isFirst) {
+        this.scrollToIndex(0, false, false, true);
+        this.setState({ currentIndex: 0 }, () => {
+          this.changeCurrentIndex(0);
+        });
+      } else {
+        const actualIndex = index - EXTRA_CAROUSEL_ITEMS;
+        this.changeInternalIndex(actualIndex);
+      }
+    } else {
+      this.changeInternalIndex(index);
+    }
+
+    if (isAutoScrolling) {
+      this.setState({ isAutoScrolling: false });
+
+      const { autoScrollRestartTimeout } = this.state;
+      if (autoScrollRestartTimeout) {
+        clearTimeout(autoScrollRestartTimeout);
+      }
+
+      const newAutoScrollRestartTimeout = setTimeout(() => {
+        this.startAutoPlay();
+        this.setState({ autoScrollRestartTimeout: null });
+      }, 100);
+      this.setState({ autoScrollRestartTimeout: newAutoScrollRestartTimeout });
+    }
   };
 
   renderCarouselItem = (item, index, array) => {
     const {
       contentHeight,
       contentWidth,
+      horizontal,
+      itemStyle,
       keyExtractor,
       keyPrefix,
-      horizontal,
       loop,
-      itemStyle,
       renderItem,
       spacing,
       visibleEdge
@@ -102,11 +224,19 @@ class CarouselComponent extends Component {
       visibleEdge
     };
 
-    const key = loop
-      ? index < EXTRA_CAROUSEL_ITEMS || index > array.length - 1
-        ? `${keyPrefix}${keyExtractor(item, index, array)}`
-        : `${keyPrefix}${index}`
-      : `${keyPrefix}${keyExtractor(item, index, array)}`;
+    let key;
+    if (loop) {
+      if (index < EXTRA_CAROUSEL_ITEMS) {
+        key = `${keyPrefix}loop-start-${index}`;
+      } else if (index >= array.length - EXTRA_CAROUSEL_ITEMS) {
+        key = `${keyPrefix}loop-end-${index}`;
+      } else {
+        const originalIndex = index - EXTRA_CAROUSEL_ITEMS;
+        key = `${keyPrefix}${keyExtractor(item, originalIndex, array)}`;
+      }
+    } else {
+      key = `${keyPrefix}${keyExtractor(item, index, array)}`;
+    }
 
     return (
       <CarouselItem {...itemProps} key={key}>
@@ -124,19 +254,23 @@ class CarouselComponent extends Component {
     return children.map(this.renderCarouselItem);
   };
 
-  scrollToIndex = (index, animated = false, disableThreshold = false) => {
+  scrollToIndex = (index, animated = false, disableThreshold = false, skipOnChange = false) => {
     if (this.ref && this.ref.current) {
-      this.changeCurrentIndex(index);
       const { contentHeight, contentWidth, horizontal, items, loop, spacing, visibleEdge } = this.props;
       if (index >= 0 - disableThreshold && index < items.length + disableThreshold) {
+        if (!skipOnChange) {
+          this.changeCurrentIndex(index);
+        }
         const indexToScrollTo = loop ? index + EXTRA_CAROUSEL_ITEMS : index;
         const scrollConfig = horizontal
           ? { x: indexToScrollTo * (contentWidth - visibleEdge * 2 - spacing) }
           : { y: indexToScrollTo * (contentHeight - visibleEdge * 2 - spacing) };
         this.ref.current.scrollTo({ ...scrollConfig, animated });
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn('The index specified is not in the item list!', index, items.length);
       }
-      // eslint-disable-next-line no-console
-    } else console.warn('The index specified is not in the item list!');
+    }
   };
 
   // eslint-disable-next-line react/no-unused-class-component-methods
@@ -179,6 +313,8 @@ class CarouselComponent extends Component {
         style={[styles.contentStyle, forcedStyles, { opacity }]}
         horizontal={horizontal}
         onScroll={this.handleScroll}
+        onTouchStart={this.handleTouchStart}
+        onTouchEnd={this.handleTouchEnd}
         overScrollMode={loop ? 'never' : 'auto'}
         pagingEnabled
         ref={this.ref}

package/lib/components/Carousel/components/CarouselComponent/utils.js

@@ -0,0 +1,2 @@
+export const validateIndex = (index, fallback = 0) =>
+  typeof index === 'number' && !Number.isNaN(index) ? index : fallback;

package/lib/components/Carousel/propTypes.js

@@ -13,6 +13,8 @@ export const carouselForcedProps = {
 
 export const carouselDefaultProps = {
   ...ScrollView.defaultProps,
+  autoPlay: false,
+  autoPlayDelay: 3000,
   contentHeight: 0,
   contentWidth: 0,
   horizontal: true, // ScrollView prop
@@ -31,6 +33,8 @@ export const carouselDefaultProps = {
 
 const propTypes = {
   ...ScrollView.propTypes,
+  autoPlay: bool,
+  autoPlayDelay: number,
   contentHeight: number,
   contentWidth: number,
   initialIndex: number.isRequired,

package/package.json

@@ -2,7 +2,7 @@
   "name": "@widergy/mobile-ui",
   "description": "Widergy Mobile Components",
   "author": "widergy",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "repository": "https://github.com/widergy/mobile-ui.git",
   "main": "lib/index.js",
   "files": [