react-native-glitter 1.0.7 → 1.0.8

package/README.md

@@ -17,10 +17,11 @@ Works with both **React Native CLI** and **Expo** projects - no native dependenc
 
 - 🚀 **Zero native dependencies** - Pure JavaScript/TypeScript implementation
 - 📱 **Cross-platform** - Works on iOS, Android, and Web
-- 🎨 **Customizable** - Control color, speed, angle, and more
+- 🎨 **Customizable** - Control color, speed, angle, opacity, and more
 - ⚡ **Performant** - Uses native driver for smooth 60fps animations
 - 🔧 **TypeScript** - Full TypeScript support with type definitions
 - ✨ **Animation Modes** - Normal, expand, and shrink effects
+- ♿ **Accessible** - Respects system "Reduce Motion" setting
 
 ## Installation
 
@@ -155,9 +156,11 @@ function ControlledGlitter() {
 | `children` | `ReactNode` | **required** | The content to apply the shimmer effect to |
 | `duration` | `number` | `1500` | Duration of one shimmer animation cycle in milliseconds |
 | `delay` | `number` | `400` | Delay between animation cycles in milliseconds |
+| `initialDelay` | `number` | `0` | Initial delay before the first animation starts (useful for staggering) |
 | `color` | `string` | `'rgba(255, 255, 255, 0.8)'` | Color of the shimmer effect |
 | `angle` | `number` | `20` | Angle of the shimmer in degrees |
 | `shimmerWidth` | `number` | `60` | Width of the shimmer band in pixels |
+| `opacity` | `number` | `1` | Overall opacity of the shimmer effect (0-1) |
 | `active` | `boolean` | `true` | Whether the animation is active |
 | `style` | `ViewStyle` | - | Additional styles for the container |
 | `easing` | `(value: number) => number` | - | Custom easing function for the animation |
@@ -167,10 +170,12 @@ function ControlledGlitter() {
 | `iterations` | `number` | `-1` | Number of animation cycles (-1 for infinite) |
 | `onAnimationStart` | `() => void` | - | Callback when animation starts |
 | `onAnimationComplete` | `() => void` | - | Callback when all iterations complete |
+| `onIterationComplete` | `(iteration: number) => void` | - | Callback when each iteration completes |
 | `testID` | `string` | - | Test ID for e2e testing |
 | `accessibilityLabel` | `string` | - | Accessibility label for screen readers |
 | `accessible` | `boolean` | `true` | Whether the component is accessible |
 | `respectReduceMotion` | `boolean` | `true` | Whether to respect the system's "Reduce Motion" setting |
+| `pauseOnBackground` | `boolean` | `true` | Whether to pause animation when app goes to background |
 
 ## Examples
 

package/lib/module/index.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState, useCallback, useMemo, memo, useImperativeHandle, forwardRef, } from 'react';
-import { View, Animated, StyleSheet, Easing, AccessibilityInfo, } from 'react-native';
+import { View, Animated, StyleSheet, Easing, AccessibilityInfo, AppState, } from 'react-native';
 function generateGlitterOpacities(count, peak = 1) {
     const opacities = [];
     const center = (count - 1) / 2;
@@ -52,11 +52,26 @@ const HEIGHT_MULTIPLIER = 1.5;
 const NORMAL_FADE_RATIO = (HEIGHT_MULTIPLIER - 1) / HEIGHT_MULTIPLIER / 2;
 const ANIMATED_SEGMENTS = generateVerticalSegments(0.25);
 const NORMAL_SEGMENTS = generateVerticalSegments(NORMAL_FADE_RATIO);
-function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgba(255, 255, 255, 0.8)', angle = 20, shimmerWidth = 60, active = true, style, easing, mode = 'normal', position = 'center', direction = 'left-to-right', iterations = -1, onAnimationStart, onAnimationComplete, testID, accessibilityLabel, accessible = true, respectReduceMotion = true, }, ref) {
+function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgba(255, 255, 255, 0.8)', angle = 20, shimmerWidth = 60, opacity: shimmerOpacity = 1, active = true, style, easing, mode = 'normal', position = 'center', direction = 'left-to-right', iterations = -1, initialDelay = 0, onAnimationStart, onAnimationComplete, onIterationComplete, testID, accessibilityLabel, accessible = true, respectReduceMotion = true, pauseOnBackground = true, }, ref) {
     const animatedValue = useRef(new Animated.Value(0)).current;
     const [containerWidth, setContainerWidth] = useState(0);
     const [containerHeight, setContainerHeight] = useState(0);
     const [reduceMotionEnabled, setReduceMotionEnabled] = useState(false);
+    const [isAppActive, setIsAppActive] = useState(true);
+    // Detect app state changes (background/foreground)
+    useEffect(() => {
+        if (!pauseOnBackground) {
+            setIsAppActive(true);
+            return;
+        }
+        const handleAppStateChange = (nextAppState) => {
+            setIsAppActive(nextAppState === 'active');
+        };
+        const subscription = AppState.addEventListener('change', handleAppStateChange);
+        return () => {
+            subscription.remove();
+        };
+    }, [pauseOnBackground]);
     // Detect system reduce motion preference
     useEffect(() => {
         if (!respectReduceMotion) {
@@ -85,11 +100,16 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
     }, [respectReduceMotion]);
     const animationRef = useRef(null);
     const currentIterationRef = useRef(null);
+    const initialDelayRef = useRef(null);
     const iterationCount = useRef(0);
     const isAnimatingRef = useRef(false);
     const defaultEasing = useMemo(() => Easing.bezier(0.4, 0, 0.2, 1), []);
     const stopAnimation = useCallback(() => {
         isAnimatingRef.current = false;
+        if (initialDelayRef.current) {
+            clearTimeout(initialDelayRef.current);
+            initialDelayRef.current = null;
+        }
         animationRef.current?.stop();
         animationRef.current = null;
         currentIterationRef.current?.stop();
@@ -113,13 +133,12 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
         isAnimating: () => isAnimatingRef.current,
     }), [stopAnimation, restartAnimation, containerWidth]);
     const startAnimation = useCallback(() => {
-        if (!active || containerWidth === 0 || reduceMotionEnabled)
+        if (!active || containerWidth === 0 || reduceMotionEnabled || !isAppActive)
             return;
         stopAnimation();
         animatedValue.setValue(0);
         iterationCount.current = 0;
         isAnimatingRef.current = true;
-        onAnimationStart?.();
         const createSingleIteration = () => Animated.sequence([
             Animated.timing(animatedValue, {
                 toValue: 1,
@@ -137,6 +156,7 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
             currentIterationRef.current.start(({ finished }) => {
                 if (finished && isAnimatingRef.current) {
                     iterationCount.current += 1;
+                    onIterationComplete?.(iterationCount.current);
                     if (iterations === -1 || iterationCount.current < iterations) {
                         runIteration();
                     }
@@ -147,26 +167,35 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
                 }
             });
         };
-        if (iterations === -1) {
-            animationRef.current = Animated.loop(createSingleIteration());
-            animationRef.current.start();
+        const beginAnimation = () => {
+            if (!isAnimatingRef.current)
+                return;
+            onAnimationStart?.();
+            runIteration();
+        };
+        // Apply initial delay before first animation
+        if (initialDelay > 0) {
+            initialDelayRef.current = setTimeout(beginAnimation, initialDelay);
         }
         else {
-            runIteration();
+            beginAnimation();
         }
     }, [
         active,
         containerWidth,
         duration,
         delay,
+        initialDelay,
         animatedValue,
         easing,
         defaultEasing,
         iterations,
         onAnimationStart,
         onAnimationComplete,
+        onIterationComplete,
         stopAnimation,
         reduceMotionEnabled,
+        isAppActive,
     ]);
     useEffect(() => {
         startAnimation();
@@ -225,7 +254,10 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
         backgroundColor: color,
         baseOpacity: segment.opacity,
     })), [segments, lineHeight, color]);
-    const shimmerContainerStyle = useMemo(() => [styles.shimmerContainer, { transform: [{ translateX }] }], [translateX]);
+    const shimmerContainerStyle = useMemo(() => [
+        styles.shimmerContainer,
+        { transform: [{ translateX }], opacity: shimmerOpacity },
+    ], [translateX, shimmerOpacity]);
     const rotationWrapperStyle = useMemo(() => [
         styles.rotationWrapper,
         {
@@ -253,6 +285,7 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
     ], [layerWidth, lineHeight, isAnimated, transformOriginOffset, scaleY]);
     return (_jsxs(View, { style: [styles.container, style], onLayout: onLayout, testID: testID, accessibilityLabel: accessibilityLabel, accessible: accessible, children: [children, active &&
                 !reduceMotionEnabled &&
+                isAppActive &&
                 containerWidth > 0 &&
                 containerHeight > 0 && (_jsx(Animated.View, { style: shimmerContainerStyle, pointerEvents: "none", children: _jsx(View, { style: rotationWrapperStyle, children: shimmerLayers.map((layer, layerIndex) => (_jsx(Animated.View, { style: getShimmerLineStyle(layer.position), children: segmentStyles.map((segmentStyle, vIndex) => (_jsx(View, { style: [
                                 styles.segment,

package/lib/typescript/src/index.d.ts

@@ -51,6 +51,13 @@ export interface GlitterProps {
      * @default 400
      */
     delay?: number;
+    /**
+     * Initial delay before the first animation cycle starts in milliseconds.
+     * Useful for staggering multiple shimmer effects.
+     * @default 0
+     * @example 500 // Wait 500ms before starting the first animation
+     */
+    initialDelay?: number;
     /**
      * Color of the shimmer effect.
      * Supports any valid React Native color format (rgba, hex, rgb, named colors).
@@ -69,6 +76,13 @@ export interface GlitterProps {
      * @default 60
      */
     shimmerWidth?: number;
+    /**
+     * Overall opacity of the shimmer effect.
+     * Value between 0 and 1.
+     * @default 1
+     * @example 0.5 // 50% opacity shimmer
+     */
+    opacity?: number;
     /**
      * Whether the animation is active.
      * Set to false to pause the animation.
@@ -119,6 +133,13 @@ export interface GlitterProps {
      * Only called when iterations is a positive number.
      */
     onAnimationComplete?: () => void;
+    /**
+     * Callback fired when each iteration completes.
+     * Receives the current iteration number (1-indexed).
+     * @param iteration - The iteration number that just completed (starts at 1)
+     * @example (iteration) => console.log(`Iteration ${iteration} completed`)
+     */
+    onIterationComplete?: (iteration: number) => void;
     /**
      * Test ID for e2e testing frameworks like Detox.
      */
@@ -139,6 +160,12 @@ export interface GlitterProps {
      * @default true
      */
     respectReduceMotion?: boolean;
+    /**
+     * Whether to pause the animation when the app goes to background.
+     * Helps save battery by stopping unnecessary animations.
+     * @default true
+     */
+    pauseOnBackground?: boolean;
 }
 /**
  * Ref methods exposed by the Glitter component for programmatic control.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-glitter",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "A beautiful shimmer/glitter effect component for React Native. Add a sparkling diagonal shine animation to any component!",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/index.tsx

@@ -17,9 +17,11 @@ import {
   StyleSheet,
   Easing,
   AccessibilityInfo,
+  AppState,
   type LayoutChangeEvent,
   type StyleProp,
   type ViewStyle,
+  type AppStateStatus,
 } from 'react-native';
 
 /**
@@ -79,6 +81,14 @@ export interface GlitterProps {
    */
   delay?: number;
 
+  /**
+   * Initial delay before the first animation cycle starts in milliseconds.
+   * Useful for staggering multiple shimmer effects.
+   * @default 0
+   * @example 500 // Wait 500ms before starting the first animation
+   */
+  initialDelay?: number;
+
   /**
    * Color of the shimmer effect.
    * Supports any valid React Native color format (rgba, hex, rgb, named colors).
@@ -100,6 +110,14 @@ export interface GlitterProps {
    */
   shimmerWidth?: number;
 
+  /**
+   * Overall opacity of the shimmer effect.
+   * Value between 0 and 1.
+   * @default 1
+   * @example 0.5 // 50% opacity shimmer
+   */
+  opacity?: number;
+
   /**
    * Whether the animation is active.
    * Set to false to pause the animation.
@@ -159,6 +177,14 @@ export interface GlitterProps {
    */
   onAnimationComplete?: () => void;
 
+  /**
+   * Callback fired when each iteration completes.
+   * Receives the current iteration number (1-indexed).
+   * @param iteration - The iteration number that just completed (starts at 1)
+   * @example (iteration) => console.log(`Iteration ${iteration} completed`)
+   */
+  onIterationComplete?: (iteration: number) => void;
+
   /**
    * Test ID for e2e testing frameworks like Detox.
    */
@@ -182,6 +208,13 @@ export interface GlitterProps {
    * @default true
    */
   respectReduceMotion?: boolean;
+
+  /**
+   * Whether to pause the animation when the app goes to background.
+   * Helps save battery by stopping unnecessary animations.
+   * @default true
+   */
+  pauseOnBackground?: boolean;
 }
 
 /**
@@ -302,6 +335,7 @@ function GlitterComponent(
     color = 'rgba(255, 255, 255, 0.8)',
     angle = 20,
     shimmerWidth = 60,
+    opacity: shimmerOpacity = 1,
     active = true,
     style,
     easing,
@@ -309,12 +343,15 @@ function GlitterComponent(
     position = 'center',
     direction = 'left-to-right',
     iterations = -1,
+    initialDelay = 0,
     onAnimationStart,
     onAnimationComplete,
+    onIterationComplete,
     testID,
     accessibilityLabel,
     accessible = true,
     respectReduceMotion = true,
+    pauseOnBackground = true,
   }: GlitterProps,
   ref: ForwardedRef<GlitterRef>
 ): ReactElement {
@@ -322,6 +359,28 @@ function GlitterComponent(
   const [containerWidth, setContainerWidth] = useState(0);
   const [containerHeight, setContainerHeight] = useState(0);
   const [reduceMotionEnabled, setReduceMotionEnabled] = useState(false);
+  const [isAppActive, setIsAppActive] = useState(true);
+
+  // Detect app state changes (background/foreground)
+  useEffect(() => {
+    if (!pauseOnBackground) {
+      setIsAppActive(true);
+      return;
+    }
+
+    const handleAppStateChange = (nextAppState: AppStateStatus) => {
+      setIsAppActive(nextAppState === 'active');
+    };
+
+    const subscription = AppState.addEventListener(
+      'change',
+      handleAppStateChange
+    );
+
+    return () => {
+      subscription.remove();
+    };
+  }, [pauseOnBackground]);
 
   // Detect system reduce motion preference
   useEffect(() => {
@@ -360,6 +419,7 @@ function GlitterComponent(
   const currentIterationRef = useRef<ReturnType<
     typeof Animated.sequence
   > | null>(null);
+  const initialDelayRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const iterationCount = useRef(0);
   const isAnimatingRef = useRef(false);
 
@@ -367,6 +427,10 @@ function GlitterComponent(
 
   const stopAnimation = useCallback(() => {
     isAnimatingRef.current = false;
+    if (initialDelayRef.current) {
+      clearTimeout(initialDelayRef.current);
+      initialDelayRef.current = null;
+    }
     animationRef.current?.stop();
     animationRef.current = null;
     currentIterationRef.current?.stop();
@@ -397,15 +461,14 @@ function GlitterComponent(
   );
 
   const startAnimation = useCallback(() => {
-    if (!active || containerWidth === 0 || reduceMotionEnabled) return;
+    if (!active || containerWidth === 0 || reduceMotionEnabled || !isAppActive)
+      return;
 
     stopAnimation();
     animatedValue.setValue(0);
     iterationCount.current = 0;
     isAnimatingRef.current = true;
 
-    onAnimationStart?.();
-
     const createSingleIteration = () =>
       Animated.sequence([
         Animated.timing(animatedValue, {
@@ -426,6 +489,8 @@ function GlitterComponent(
         ({ finished }: { finished: boolean }) => {
           if (finished && isAnimatingRef.current) {
             iterationCount.current += 1;
+            onIterationComplete?.(iterationCount.current);
+
             if (iterations === -1 || iterationCount.current < iterations) {
               runIteration();
             } else {
@@ -437,25 +502,35 @@ function GlitterComponent(
       );
     };
 
-    if (iterations === -1) {
-      animationRef.current = Animated.loop(createSingleIteration());
-      animationRef.current.start();
-    } else {
+    const beginAnimation = () => {
+      if (!isAnimatingRef.current) return;
+
+      onAnimationStart?.();
       runIteration();
+    };
+
+    // Apply initial delay before first animation
+    if (initialDelay > 0) {
+      initialDelayRef.current = setTimeout(beginAnimation, initialDelay);
+    } else {
+      beginAnimation();
     }
   }, [
     active,
     containerWidth,
     duration,
     delay,
+    initialDelay,
     animatedValue,
     easing,
     defaultEasing,
     iterations,
     onAnimationStart,
     onAnimationComplete,
+    onIterationComplete,
     stopAnimation,
     reduceMotionEnabled,
+    isAppActive,
   ]);
 
   useEffect(() => {
@@ -559,8 +634,11 @@ function GlitterComponent(
   );
 
   const shimmerContainerStyle = useMemo(
-    () => [styles.shimmerContainer, { transform: [{ translateX }] }],
-    [translateX]
+    () => [
+      styles.shimmerContainer,
+      { transform: [{ translateX }], opacity: shimmerOpacity },
+    ],
+    [translateX, shimmerOpacity]
   );
 
   const rotationWrapperStyle = useMemo(
@@ -607,6 +685,7 @@ function GlitterComponent(
       {children}
       {active &&
         !reduceMotionEnabled &&
+        isAppActive &&
         containerWidth > 0 &&
         containerHeight > 0 && (
           <Animated.View style={shimmerContainerStyle} pointerEvents="none">