react-native-glitter 1.0.5 → 1.0.7

package/README.md

@@ -170,6 +170,7 @@ function ControlledGlitter() {
 | `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 |
 
 ## 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, } from 'react-native';
+import { View, Animated, StyleSheet, Easing, AccessibilityInfo, } from 'react-native';
 function generateGlitterOpacities(count, peak = 1) {
     const opacities = [];
     const center = (count - 1) / 2;
@@ -52,10 +52,37 @@ 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, }, ref) {
+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) {
     const animatedValue = useRef(new Animated.Value(0)).current;
     const [containerWidth, setContainerWidth] = useState(0);
     const [containerHeight, setContainerHeight] = useState(0);
+    const [reduceMotionEnabled, setReduceMotionEnabled] = useState(false);
+    // Detect system reduce motion preference
+    useEffect(() => {
+        if (!respectReduceMotion) {
+            setReduceMotionEnabled(false);
+            return;
+        }
+        let isMounted = true;
+        AccessibilityInfo.isReduceMotionEnabled()
+            .then((enabled) => {
+            if (isMounted) {
+                setReduceMotionEnabled(enabled);
+            }
+        })
+            .catch(() => {
+            // Ignore errors (e.g., on web where this might not be supported)
+        });
+        const subscription = AccessibilityInfo.addEventListener('reduceMotionChanged', (enabled) => {
+            if (isMounted) {
+                setReduceMotionEnabled(enabled);
+            }
+        });
+        return () => {
+            isMounted = false;
+            subscription.remove();
+        };
+    }, [respectReduceMotion]);
     const animationRef = useRef(null);
     const currentIterationRef = useRef(null);
     const iterationCount = useRef(0);
@@ -86,7 +113,7 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
         isAnimating: () => isAnimatingRef.current,
     }), [stopAnimation, restartAnimation, containerWidth]);
     const startAnimation = useCallback(() => {
-        if (!active || containerWidth === 0)
+        if (!active || containerWidth === 0 || reduceMotionEnabled)
             return;
         stopAnimation();
         animatedValue.setValue(0);
@@ -139,6 +166,7 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
         onAnimationStart,
         onAnimationComplete,
         stopAnimation,
+        reduceMotionEnabled,
     ]);
     useEffect(() => {
         startAnimation();
@@ -180,7 +208,9 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
         }
         return position === 'top' ? -halfHeight : halfHeight;
     }, [mode, position, halfHeight]);
-    const layerCount = useMemo(() => Math.max(11, Math.round(shimmerWidth / 3)), [shimmerWidth]);
+    // Optimized: reduced layer count for better performance
+    // shimmerWidth=60 → 12 layers (was 20), shimmerWidth=100 → 14 layers (was 33)
+    const layerCount = useMemo(() => Math.max(7, Math.round(shimmerWidth / 5)), [shimmerWidth]);
     const layerWidth = useMemo(() => shimmerWidth / layerCount, [shimmerWidth, layerCount]);
     const horizontalOpacities = useMemo(() => generateGlitterOpacities(layerCount, 1), [layerCount]);
     const shimmerLayers = useMemo(() => horizontalOpacities.map((opacity, index) => ({
@@ -189,6 +219,12 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
     })), [horizontalOpacities, layerWidth, shimmerWidth]);
     const isAnimated = mode !== 'normal';
     const segments = isAnimated ? ANIMATED_SEGMENTS : NORMAL_SEGMENTS;
+    // Memoize segment styles to avoid creating new objects on every render
+    const segmentStyles = useMemo(() => segments.map((segment) => ({
+        height: lineHeight * segment.heightRatio,
+        backgroundColor: color,
+        baseOpacity: segment.opacity,
+    })), [segments, lineHeight, color]);
     const shimmerContainerStyle = useMemo(() => [styles.shimmerContainer, { transform: [{ translateX }] }], [translateX]);
     const rotationWrapperStyle = useMemo(() => [
         styles.rotationWrapper,
@@ -215,12 +251,15 @@ 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 && 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: segments.map((segment, vIndex) => (_jsx(View, { style: [
+    return (_jsxs(View, { style: [styles.container, style], onLayout: onLayout, testID: testID, accessibilityLabel: accessibilityLabel, accessible: accessible, children: [children, active &&
+                !reduceMotionEnabled &&
+                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,
                                 {
-                                    height: lineHeight * segment.heightRatio,
-                                    backgroundColor: color,
-                                    opacity: layer.opacity * segment.opacity,
+                                    height: segmentStyle.height,
+                                    backgroundColor: segmentStyle.backgroundColor,
+                                    opacity: layer.opacity * segmentStyle.baseOpacity,
                                 },
                             ] }, vIndex))) }, layerIndex))) }) }))] }));
 }
@@ -249,5 +288,41 @@ const styles = StyleSheet.create({
     },
 });
 const ForwardedGlitter = forwardRef(GlitterComponent);
+/**
+ * A beautiful shimmer/glitter effect component for React Native.
+ * Wrap any component to add a sparkling diagonal shine animation.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Glitter>
+ *   <View style={styles.card}>
+ *     <Text>This content will shimmer!</Text>
+ *   </View>
+ * </Glitter>
+ *
+ * // With custom options
+ * <Glitter
+ *   duration={2000}
+ *   color="rgba(255, 215, 0, 0.5)"
+ *   mode="expand"
+ *   direction="right-to-left"
+ * >
+ *   <View style={styles.premiumButton} />
+ * </Glitter>
+ *
+ * // With ref for programmatic control
+ * const glitterRef = useRef<GlitterRef>(null);
+ * <Glitter ref={glitterRef} active={false}>
+ *   <View style={styles.box} />
+ * </Glitter>
+ * // Later: glitterRef.current?.start();
+ * ```
+ *
+ * @see {@link GlitterProps} for available props
+ * @see {@link GlitterRef} for ref methods
+ */
 export const Glitter = memo(ForwardedGlitter);
+// Set display name for React DevTools
+Glitter.displayName = 'Glitter';
 export default Glitter;

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

@@ -1,41 +1,218 @@
 import { type ReactNode } from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
+/**
+ * Animation mode for the shimmer effect.
+ * - `normal`: Constant size shimmer line
+ * - `expand`: Shimmer line starts small and grows
+ * - `shrink`: Shimmer line starts full size and shrinks
+ */
 export type GlitterMode = 'normal' | 'expand' | 'shrink';
+/**
+ * Position where the shimmer line shrinks to or expands from.
+ * Only applies when mode is 'expand' or 'shrink'.
+ * - `top`: Shrinks to/expands from the top
+ * - `center`: Shrinks to/expands from the center
+ * - `bottom`: Shrinks to/expands from the bottom
+ */
 export type GlitterPosition = 'top' | 'center' | 'bottom';
+/**
+ * Direction of the shimmer animation movement.
+ * - `left-to-right`: Shimmer moves from left to right
+ * - `right-to-left`: Shimmer moves from right to left
+ */
 export type GlitterDirection = 'left-to-right' | 'right-to-left';
+/**
+ * Props for the Glitter component.
+ *
+ * @example
+ * ```tsx
+ * <Glitter
+ *   duration={1500}
+ *   color="rgba(255, 255, 255, 0.8)"
+ *   mode="expand"
+ * >
+ *   <View style={styles.card} />
+ * </Glitter>
+ * ```
+ */
 export interface GlitterProps {
+    /**
+     * The content to apply the shimmer effect to.
+     * Can be any valid React node.
+     */
     children: ReactNode;
+    /**
+     * Duration of one shimmer animation cycle in milliseconds.
+     * @default 1500
+     */
     duration?: number;
+    /**
+     * Delay between animation cycles in milliseconds.
+     * @default 400
+     */
     delay?: number;
+    /**
+     * Color of the shimmer effect.
+     * Supports any valid React Native color format (rgba, hex, rgb, named colors).
+     * @default 'rgba(255, 255, 255, 0.8)'
+     * @example 'rgba(255, 215, 0, 0.5)' // Gold shimmer
+     */
     color?: string;
+    /**
+     * Angle of the shimmer in degrees.
+     * 0 = horizontal, 45 = diagonal.
+     * @default 20
+     */
     angle?: number;
+    /**
+     * Width of the shimmer band in pixels.
+     * @default 60
+     */
     shimmerWidth?: number;
+    /**
+     * Whether the animation is active.
+     * Set to false to pause the animation.
+     * @default true
+     */
     active?: boolean;
+    /**
+     * Additional styles for the container View.
+     */
     style?: StyleProp<ViewStyle>;
+    /**
+     * Custom easing function for the animation.
+     * If not provided, uses a smooth bezier curve (0.4, 0, 0.2, 1).
+     * @param value - Input value between 0 and 1
+     * @returns Output value between 0 and 1
+     * @example (value) => value * value // Ease in quad
+     */
     easing?: (value: number) => number;
+    /**
+     * Animation mode for the shimmer line.
+     * @default 'normal'
+     */
     mode?: GlitterMode;
+    /**
+     * Position where the line shrinks/expands.
+     * Only applies when mode is 'expand' or 'shrink'.
+     * @default 'center'
+     */
     position?: GlitterPosition;
+    /**
+     * Direction of the shimmer animation.
+     * @default 'left-to-right'
+     */
     direction?: GlitterDirection;
+    /**
+     * Number of animation cycles.
+     * Set to -1 for infinite loop.
+     * @default -1
+     */
     iterations?: number;
+    /**
+     * Callback fired when the animation starts.
+     * Called once at the beginning of the animation sequence.
+     */
     onAnimationStart?: () => void;
+    /**
+     * Callback fired when all iterations complete.
+     * Only called when iterations is a positive number.
+     */
     onAnimationComplete?: () => void;
-    /** Test ID for e2e testing */
+    /**
+     * Test ID for e2e testing frameworks like Detox.
+     */
     testID?: string;
-    /** Accessibility label for screen readers */
+    /**
+     * Accessibility label for screen readers.
+     * Describes the shimmer effect to visually impaired users.
+     */
     accessibilityLabel?: string;
-    /** Whether the component is accessible (default: true) */
+    /**
+     * Whether the component is accessible.
+     * @default true
+     */
     accessible?: boolean;
+    /**
+     * Whether to respect the system's "Reduce Motion" accessibility setting.
+     * When enabled and the user has reduced motion enabled, the shimmer animation will be disabled.
+     * @default true
+     */
+    respectReduceMotion?: boolean;
 }
-/** Ref methods exposed by Glitter component */
+/**
+ * Ref methods exposed by the Glitter component for programmatic control.
+ *
+ * @example
+ * ```tsx
+ * const glitterRef = useRef<GlitterRef>(null);
+ *
+ * // Control animation programmatically
+ * glitterRef.current?.start();
+ * glitterRef.current?.stop();
+ * glitterRef.current?.restart();
+ *
+ * // Check animation status
+ * if (glitterRef.current?.isAnimating()) {
+ *   console.log('Animation is running');
+ * }
+ * ```
+ */
 export interface GlitterRef {
-    /** Start the shimmer animation */
+    /**
+     * Start the shimmer animation.
+     * Has no effect if already animating or container has no size.
+     */
     start: () => void;
-    /** Stop the shimmer animation */
+    /**
+     * Stop the shimmer animation immediately.
+     * Cleans up all animation references.
+     */
     stop: () => void;
-    /** Restart the shimmer animation from the beginning */
+    /**
+     * Restart the shimmer animation from the beginning.
+     * Stops current animation and starts fresh.
+     */
     restart: () => void;
-    /** Check if animation is currently running */
+    /**
+     * Check if animation is currently running.
+     * @returns true if animation is active, false otherwise
+     */
     isAnimating: () => boolean;
 }
+/**
+ * A beautiful shimmer/glitter effect component for React Native.
+ * Wrap any component to add a sparkling diagonal shine animation.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Glitter>
+ *   <View style={styles.card}>
+ *     <Text>This content will shimmer!</Text>
+ *   </View>
+ * </Glitter>
+ *
+ * // With custom options
+ * <Glitter
+ *   duration={2000}
+ *   color="rgba(255, 215, 0, 0.5)"
+ *   mode="expand"
+ *   direction="right-to-left"
+ * >
+ *   <View style={styles.premiumButton} />
+ * </Glitter>
+ *
+ * // With ref for programmatic control
+ * const glitterRef = useRef<GlitterRef>(null);
+ * <Glitter ref={glitterRef} active={false}>
+ *   <View style={styles.box} />
+ * </Glitter>
+ * // Later: glitterRef.current?.start();
+ * ```
+ *
+ * @see {@link GlitterProps} for available props
+ * @see {@link GlitterRef} for ref methods
+ */
 export declare const Glitter: import("react").NamedExoticComponent<GlitterProps & import("react").RefAttributes<GlitterRef>>;
 export default Glitter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-glitter",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "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",
@@ -15,17 +15,6 @@
   "files": [
     "src",
     "lib",
-    "android",
-    "ios",
-    "cpp",
-    "*.podspec",
-    "react-native.config.js",
-    "!ios/build",
-    "!android/build",
-    "!android/gradle",
-    "!android/gradlew",
-    "!android/gradlew.bat",
-    "!android/local.properties",
     "!**/__tests__",
     "!**/__fixtures__",
     "!**/__mocks__",

package/src/index.tsx

@@ -16,50 +16,215 @@ import {
   Animated,
   StyleSheet,
   Easing,
+  AccessibilityInfo,
   type LayoutChangeEvent,
   type StyleProp,
   type ViewStyle,
 } from 'react-native';
 
+/**
+ * Animation mode for the shimmer effect.
+ * - `normal`: Constant size shimmer line
+ * - `expand`: Shimmer line starts small and grows
+ * - `shrink`: Shimmer line starts full size and shrinks
+ */
 export type GlitterMode = 'normal' | 'expand' | 'shrink';
 
+/**
+ * Position where the shimmer line shrinks to or expands from.
+ * Only applies when mode is 'expand' or 'shrink'.
+ * - `top`: Shrinks to/expands from the top
+ * - `center`: Shrinks to/expands from the center
+ * - `bottom`: Shrinks to/expands from the bottom
+ */
 export type GlitterPosition = 'top' | 'center' | 'bottom';
 
+/**
+ * Direction of the shimmer animation movement.
+ * - `left-to-right`: Shimmer moves from left to right
+ * - `right-to-left`: Shimmer moves from right to left
+ */
 export type GlitterDirection = 'left-to-right' | 'right-to-left';
 
+/**
+ * Props for the Glitter component.
+ *
+ * @example
+ * ```tsx
+ * <Glitter
+ *   duration={1500}
+ *   color="rgba(255, 255, 255, 0.8)"
+ *   mode="expand"
+ * >
+ *   <View style={styles.card} />
+ * </Glitter>
+ * ```
+ */
 export interface GlitterProps {
+  /**
+   * The content to apply the shimmer effect to.
+   * Can be any valid React node.
+   */
   children: ReactNode;
+
+  /**
+   * Duration of one shimmer animation cycle in milliseconds.
+   * @default 1500
+   */
   duration?: number;
+
+  /**
+   * Delay between animation cycles in milliseconds.
+   * @default 400
+   */
   delay?: number;
+
+  /**
+   * Color of the shimmer effect.
+   * Supports any valid React Native color format (rgba, hex, rgb, named colors).
+   * @default 'rgba(255, 255, 255, 0.8)'
+   * @example 'rgba(255, 215, 0, 0.5)' // Gold shimmer
+   */
   color?: string;
+
+  /**
+   * Angle of the shimmer in degrees.
+   * 0 = horizontal, 45 = diagonal.
+   * @default 20
+   */
   angle?: number;
+
+  /**
+   * Width of the shimmer band in pixels.
+   * @default 60
+   */
   shimmerWidth?: number;
+
+  /**
+   * Whether the animation is active.
+   * Set to false to pause the animation.
+   * @default true
+   */
   active?: boolean;
+
+  /**
+   * Additional styles for the container View.
+   */
   style?: StyleProp<ViewStyle>;
+
+  /**
+   * Custom easing function for the animation.
+   * If not provided, uses a smooth bezier curve (0.4, 0, 0.2, 1).
+   * @param value - Input value between 0 and 1
+   * @returns Output value between 0 and 1
+   * @example (value) => value * value // Ease in quad
+   */
   easing?: (value: number) => number;
+
+  /**
+   * Animation mode for the shimmer line.
+   * @default 'normal'
+   */
   mode?: GlitterMode;
+
+  /**
+   * Position where the line shrinks/expands.
+   * Only applies when mode is 'expand' or 'shrink'.
+   * @default 'center'
+   */
   position?: GlitterPosition;
+
+  /**
+   * Direction of the shimmer animation.
+   * @default 'left-to-right'
+   */
   direction?: GlitterDirection;
+
+  /**
+   * Number of animation cycles.
+   * Set to -1 for infinite loop.
+   * @default -1
+   */
   iterations?: number;
+
+  /**
+   * Callback fired when the animation starts.
+   * Called once at the beginning of the animation sequence.
+   */
   onAnimationStart?: () => void;
+
+  /**
+   * Callback fired when all iterations complete.
+   * Only called when iterations is a positive number.
+   */
   onAnimationComplete?: () => void;
-  /** Test ID for e2e testing */
+
+  /**
+   * Test ID for e2e testing frameworks like Detox.
+   */
   testID?: string;
-  /** Accessibility label for screen readers */
+
+  /**
+   * Accessibility label for screen readers.
+   * Describes the shimmer effect to visually impaired users.
+   */
   accessibilityLabel?: string;
-  /** Whether the component is accessible (default: true) */
+
+  /**
+   * Whether the component is accessible.
+   * @default true
+   */
   accessible?: boolean;
+
+  /**
+   * Whether to respect the system's "Reduce Motion" accessibility setting.
+   * When enabled and the user has reduced motion enabled, the shimmer animation will be disabled.
+   * @default true
+   */
+  respectReduceMotion?: boolean;
 }
 
-/** Ref methods exposed by Glitter component */
+/**
+ * Ref methods exposed by the Glitter component for programmatic control.
+ *
+ * @example
+ * ```tsx
+ * const glitterRef = useRef<GlitterRef>(null);
+ *
+ * // Control animation programmatically
+ * glitterRef.current?.start();
+ * glitterRef.current?.stop();
+ * glitterRef.current?.restart();
+ *
+ * // Check animation status
+ * if (glitterRef.current?.isAnimating()) {
+ *   console.log('Animation is running');
+ * }
+ * ```
+ */
 export interface GlitterRef {
-  /** Start the shimmer animation */
+  /**
+   * Start the shimmer animation.
+   * Has no effect if already animating or container has no size.
+   */
   start: () => void;
-  /** Stop the shimmer animation */
+
+  /**
+   * Stop the shimmer animation immediately.
+   * Cleans up all animation references.
+   */
   stop: () => void;
-  /** Restart the shimmer animation from the beginning */
+
+  /**
+   * Restart the shimmer animation from the beginning.
+   * Stops current animation and starts fresh.
+   */
   restart: () => void;
-  /** Check if animation is currently running */
+
+  /**
+   * Check if animation is currently running.
+   * @returns true if animation is active, false otherwise
+   */
   isAnimating: () => boolean;
 }
 
@@ -149,12 +314,48 @@ function GlitterComponent(
     testID,
     accessibilityLabel,
     accessible = true,
+    respectReduceMotion = true,
   }: GlitterProps,
   ref: ForwardedRef<GlitterRef>
 ): ReactElement {
   const animatedValue = useRef(new Animated.Value(0)).current;
   const [containerWidth, setContainerWidth] = useState(0);
   const [containerHeight, setContainerHeight] = useState(0);
+  const [reduceMotionEnabled, setReduceMotionEnabled] = useState(false);
+
+  // Detect system reduce motion preference
+  useEffect(() => {
+    if (!respectReduceMotion) {
+      setReduceMotionEnabled(false);
+      return;
+    }
+
+    let isMounted = true;
+
+    AccessibilityInfo.isReduceMotionEnabled()
+      .then((enabled) => {
+        if (isMounted) {
+          setReduceMotionEnabled(enabled);
+        }
+      })
+      .catch(() => {
+        // Ignore errors (e.g., on web where this might not be supported)
+      });
+
+    const subscription = AccessibilityInfo.addEventListener(
+      'reduceMotionChanged',
+      (enabled) => {
+        if (isMounted) {
+          setReduceMotionEnabled(enabled);
+        }
+      }
+    );
+
+    return () => {
+      isMounted = false;
+      subscription.remove();
+    };
+  }, [respectReduceMotion]);
   const animationRef = useRef<ReturnType<typeof Animated.loop> | null>(null);
   const currentIterationRef = useRef<ReturnType<
     typeof Animated.sequence
@@ -196,7 +397,7 @@ function GlitterComponent(
   );
 
   const startAnimation = useCallback(() => {
-    if (!active || containerWidth === 0) return;
+    if (!active || containerWidth === 0 || reduceMotionEnabled) return;
 
     stopAnimation();
     animatedValue.setValue(0);
@@ -254,6 +455,7 @@ function GlitterComponent(
     onAnimationStart,
     onAnimationComplete,
     stopAnimation,
+    reduceMotionEnabled,
   ]);
 
   useEffect(() => {
@@ -316,8 +518,10 @@ function GlitterComponent(
     return position === 'top' ? -halfHeight : halfHeight;
   }, [mode, position, halfHeight]);
 
+  // Optimized: reduced layer count for better performance
+  // shimmerWidth=60 → 12 layers (was 20), shimmerWidth=100 → 14 layers (was 33)
   const layerCount = useMemo(
-    () => Math.max(11, Math.round(shimmerWidth / 3)),
+    () => Math.max(7, Math.round(shimmerWidth / 5)),
     [shimmerWidth]
   );
 
@@ -343,6 +547,17 @@ function GlitterComponent(
   const isAnimated = mode !== 'normal';
   const segments = isAnimated ? ANIMATED_SEGMENTS : NORMAL_SEGMENTS;
 
+  // Memoize segment styles to avoid creating new objects on every render
+  const segmentStyles = useMemo(
+    () =>
+      segments.map((segment) => ({
+        height: lineHeight * segment.heightRatio,
+        backgroundColor: color,
+        baseOpacity: segment.opacity,
+      })),
+    [segments, lineHeight, color]
+  );
+
   const shimmerContainerStyle = useMemo(
     () => [styles.shimmerContainer, { transform: [{ translateX }] }],
     [translateX]
@@ -390,32 +605,35 @@ function GlitterComponent(
       accessible={accessible}
     >
       {children}
-      {active && containerWidth > 0 && containerHeight > 0 && (
-        <Animated.View style={shimmerContainerStyle} pointerEvents="none">
-          <View style={rotationWrapperStyle}>
-            {shimmerLayers.map((layer, layerIndex) => (
-              <Animated.View
-                key={layerIndex}
-                style={getShimmerLineStyle(layer.position)}
-              >
-                {segments.map((segment, vIndex) => (
-                  <View
-                    key={vIndex}
-                    style={[
-                      styles.segment,
-                      {
-                        height: lineHeight * segment.heightRatio,
-                        backgroundColor: color,
-                        opacity: layer.opacity * segment.opacity,
-                      },
-                    ]}
-                  />
-                ))}
-              </Animated.View>
-            ))}
-          </View>
-        </Animated.View>
-      )}
+      {active &&
+        !reduceMotionEnabled &&
+        containerWidth > 0 &&
+        containerHeight > 0 && (
+          <Animated.View style={shimmerContainerStyle} pointerEvents="none">
+            <View style={rotationWrapperStyle}>
+              {shimmerLayers.map((layer, layerIndex) => (
+                <Animated.View
+                  key={layerIndex}
+                  style={getShimmerLineStyle(layer.position)}
+                >
+                  {segmentStyles.map((segmentStyle, vIndex) => (
+                    <View
+                      key={vIndex}
+                      style={[
+                        styles.segment,
+                        {
+                          height: segmentStyle.height,
+                          backgroundColor: segmentStyle.backgroundColor,
+                          opacity: layer.opacity * segmentStyle.baseOpacity,
+                        },
+                      ]}
+                    />
+                  ))}
+                </Animated.View>
+              ))}
+            </View>
+          </Animated.View>
+        )}
     </View>
   );
 }
@@ -446,6 +664,44 @@ const styles = StyleSheet.create({
 });
 
 const ForwardedGlitter = forwardRef(GlitterComponent);
+
+/**
+ * A beautiful shimmer/glitter effect component for React Native.
+ * Wrap any component to add a sparkling diagonal shine animation.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Glitter>
+ *   <View style={styles.card}>
+ *     <Text>This content will shimmer!</Text>
+ *   </View>
+ * </Glitter>
+ *
+ * // With custom options
+ * <Glitter
+ *   duration={2000}
+ *   color="rgba(255, 215, 0, 0.5)"
+ *   mode="expand"
+ *   direction="right-to-left"
+ * >
+ *   <View style={styles.premiumButton} />
+ * </Glitter>
+ *
+ * // With ref for programmatic control
+ * const glitterRef = useRef<GlitterRef>(null);
+ * <Glitter ref={glitterRef} active={false}>
+ *   <View style={styles.box} />
+ * </Glitter>
+ * // Later: glitterRef.current?.start();
+ * ```
+ *
+ * @see {@link GlitterProps} for available props
+ * @see {@link GlitterRef} for ref methods
+ */
 export const Glitter = memo(ForwardedGlitter);
 
+// Set display name for React DevTools
+Glitter.displayName = 'Glitter';
+
 export default Glitter;