react-native-glitter 1.0.4 → 1.0.6

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
 
@@ -264,6 +265,44 @@ function ControlledGlitter() {
 </Glitter>
 ```
 
+## Ref API
+
+You can control the animation programmatically using a ref:
+
+```tsx
+import { useRef } from 'react';
+import { Glitter, type GlitterRef } from 'react-native-glitter';
+
+function MyComponent() {
+  const glitterRef = useRef<GlitterRef>(null);
+
+  const handleStart = () => glitterRef.current?.start();
+  const handleStop = () => glitterRef.current?.stop();
+  const handleRestart = () => glitterRef.current?.restart();
+  const checkStatus = () => console.log(glitterRef.current?.isAnimating());
+
+  return (
+    <>
+      <Glitter ref={glitterRef} active={false}>
+        <View style={styles.box} />
+      </Glitter>
+      <Button title="Start" onPress={handleStart} />
+      <Button title="Stop" onPress={handleStop} />
+      <Button title="Restart" onPress={handleRestart} />
+    </>
+  );
+}
+```
+
+### Ref Methods
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `start()` | `void` | Start the shimmer animation |
+| `stop()` | `void` | Stop the shimmer animation |
+| `restart()` | `void` | Restart the animation from the beginning |
+| `isAnimating()` | `boolean` | Check if animation is currently running |
+
 ## TypeScript
 
 This library is written in TypeScript and includes type definitions:
@@ -272,6 +311,7 @@ This library is written in TypeScript and includes type definitions:
 import {
   Glitter,
   type GlitterProps,
+  type GlitterRef,
   type GlitterMode,
   type GlitterPosition,
   type GlitterDirection,

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, } from 'react';
-import { View, Animated, StyleSheet, Easing, } from 'react-native';
+import { useEffect, useRef, useState, useCallback, useMemo, memo, useImperativeHandle, forwardRef, } from 'react';
+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, }) {
+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);
@@ -68,8 +95,25 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
         currentIterationRef.current?.stop();
         currentIterationRef.current = null;
     }, []);
+    const restartAnimation = useCallback(() => {
+        stopAnimation();
+        animatedValue.setValue(0);
+        // Trigger re-render to start animation
+        setContainerWidth((prev) => prev);
+    }, [stopAnimation, animatedValue]);
+    useImperativeHandle(ref, () => ({
+        start: () => {
+            if (!isAnimatingRef.current && containerWidth > 0) {
+                // Force start by triggering the effect
+                setContainerWidth((prev) => prev);
+            }
+        },
+        stop: stopAnimation,
+        restart: restartAnimation,
+        isAnimating: () => isAnimatingRef.current,
+    }), [stopAnimation, restartAnimation, containerWidth]);
     const startAnimation = useCallback(() => {
-        if (!active || containerWidth === 0)
+        if (!active || containerWidth === 0 || reduceMotionEnabled)
             return;
         stopAnimation();
         animatedValue.setValue(0);
@@ -122,6 +166,7 @@ function GlitterComponent({ children, duration = 1500, delay = 400, color = 'rgb
         onAnimationStart,
         onAnimationComplete,
         stopAnimation,
+        reduceMotionEnabled,
     ]);
     useEffect(() => {
         startAnimation();
@@ -198,7 +243,10 @@ 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: segments.map((segment, vIndex) => (_jsx(View, { style: [
                                 styles.segment,
                                 {
                                     height: lineHeight * segment.heightRatio,
@@ -231,5 +279,42 @@ const styles = StyleSheet.create({
         width: '100%',
     },
 });
-export const Glitter = memo(GlitterComponent);
+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,31 +1,218 @@
-import { type ReactNode, type ReactElement } from 'react';
+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;
 }
-declare function GlitterComponent({ children, duration, delay, color, angle, shimmerWidth, active, style, easing, mode, position, direction, iterations, onAnimationStart, onAnimationComplete, testID, accessibilityLabel, accessible, }: GlitterProps): ReactElement;
-export declare const Glitter: import("react").MemoExoticComponent<typeof GlitterComponent>;
+/**
+ * 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.
+     * Has no effect if already animating or container has no size.
+     */
+    start: () => void;
+    /**
+     * Stop the shimmer animation immediately.
+     * Cleans up all animation references.
+     */
+    stop: () => void;
+    /**
+     * Restart the shimmer animation from the beginning.
+     * Stops current animation and starts fresh.
+     */
+    restart: () => void;
+    /**
+     * 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.4",
+  "version": "1.0.6",
   "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

@@ -5,47 +5,227 @@ import {
   useCallback,
   useMemo,
   memo,
+  useImperativeHandle,
+  forwardRef,
   type ReactNode,
   type ReactElement,
+  type ForwardedRef,
 } from 'react';
 import {
   View,
   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 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.
+   * Has no effect if already animating or container has no size.
+   */
+  start: () => void;
+
+  /**
+   * Stop the shimmer animation immediately.
+   * Cleans up all animation references.
+   */
+  stop: () => void;
+
+  /**
+   * Restart the shimmer animation from the beginning.
+   * Stops current animation and starts fresh.
+   */
+  restart: () => void;
+
+  /**
+   * Check if animation is currently running.
+   * @returns true if animation is active, false otherwise
+   */
+  isAnimating: () => boolean;
 }
 
 function generateGlitterOpacities(count: number, peak: number = 1): number[] {
@@ -114,29 +294,68 @@ 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,
-}: GlitterProps): ReactElement {
+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,
+  }: 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
@@ -154,8 +373,31 @@ function GlitterComponent({
     currentIterationRef.current = null;
   }, []);
 
+  const restartAnimation = useCallback(() => {
+    stopAnimation();
+    animatedValue.setValue(0);
+    // Trigger re-render to start animation
+    setContainerWidth((prev) => prev);
+  }, [stopAnimation, animatedValue]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      start: () => {
+        if (!isAnimatingRef.current && containerWidth > 0) {
+          // Force start by triggering the effect
+          setContainerWidth((prev) => prev);
+        }
+      },
+      stop: stopAnimation,
+      restart: restartAnimation,
+      isAnimating: () => isAnimatingRef.current,
+    }),
+    [stopAnimation, restartAnimation, containerWidth]
+  );
+
   const startAnimation = useCallback(() => {
-    if (!active || containerWidth === 0) return;
+    if (!active || containerWidth === 0 || reduceMotionEnabled) return;
 
     stopAnimation();
     animatedValue.setValue(0);
@@ -213,6 +455,7 @@ function GlitterComponent({
     onAnimationStart,
     onAnimationComplete,
     stopAnimation,
+    reduceMotionEnabled,
   ]);
 
   useEffect(() => {
@@ -349,32 +592,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)}
+                >
+                  {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>
+        )}
     </View>
   );
 }
@@ -404,6 +650,45 @@ const styles = StyleSheet.create({
   },
 });
 
-export const Glitter = memo(GlitterComponent);
+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;