feat: added native toggle to turn haptics on/off

Author: AlirezaHadjar

README.md

@@ -192,7 +192,33 @@ export function SomeScreen() {
 }
 ```
 
-## API (tables)
+### Global enable/disable (settings toggle)
+
+Disable haptics globally for users who prefer no haptic feedback. The setting is **persisted** across app restarts. When disabled, all haptic calls become no-ops.
+
+**Using the hook (recommended):**
+
+```tsx
+import { useHapticsEnabled } from 'react-native-ahaps';
+
+function SettingsScreen() {
+  const [hapticsEnabled, setHapticsEnabled] = useHapticsEnabled();
+
+  return <Switch value={hapticsEnabled} onValueChange={setHapticsEnabled} />;
+}
+```
+
+**Manual control:**
+
+```ts
+import { setHapticsEnabled, getHapticsEnabled } from 'react-native-ahaps';
+
+const isEnabled = getHapticsEnabled(); // true by default
+setHapticsEnabled(false); // Disable all haptics
+setHapticsEnabled(true); // Re-enable haptics
+```
+
+## API
 
 | Function                                                               | Purpose                                                         |
 | ---------------------------------------------------------------------- | --------------------------------------------------------------- |
@@ -201,6 +227,8 @@ export function SomeScreen() {
 | `initializeEngine()` / `destroyEngine()`                               | Manual engine lifecycle                                         |
 | `startHaptic(events, curves)`                                          | Play a pattern (transient + continuous events, optional curves) |
 | `stopAllHaptics()`                                                     | Stop any running haptics (useful on unmount/navigation)         |
+| `useHapticsEnabled()`                                                  | Hook for reactive haptics enabled state                         |
+| `setHapticsEnabled(enabled)` / `getHapticsEnabled()`                   | Manual enable/disable toggle (persisted)                        |
 | `useContinuousPlayer(playerId, initialIntensity, initialSharpness)`    | Hook to manage a continuous player lifecycle                    |
 | `createContinuousPlayer(playerId, initialIntensity, initialSharpness)` | Create a continuous player with given ID                        |
 | `startContinuousPlayer(playerId)` / `stopContinuousPlayer(playerId)`   | Start/stop continuous playback for player                       |

example/src/screens/Menu.tsx

@@ -1,12 +1,14 @@
-import { View, Text, StyleSheet, TouchableOpacity } from 'react-native';
+import { View, Text, StyleSheet, TouchableOpacity, Switch } from 'react-native';
 import { useRouter } from 'expo-router';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { useTheme } from '../contexts/ThemeContext';
+import { useHapticsEnabled } from 'react-native-ahaps';
 
 export function Menu() {
   const router = useRouter();
   const insets = useSafeAreaInsets();
   const { colors } = useTheme();
+  const [hapticsEnabled, setHapticsEnabled] = useHapticsEnabled();
 
   return (
     <View
@@ -63,6 +65,17 @@ export function Menu() {
             Record haptics in real-time using touch gestures
           </Text>
         </TouchableOpacity>
+
+        <View style={[styles.toggleItem, { backgroundColor: colors.card }]}>
+          <Text style={[styles.toggleText, { color: colors.text }]}>
+            Haptics {hapticsEnabled ? 'Enabled' : 'Disabled'}
+          </Text>
+          <Switch
+            value={hapticsEnabled}
+            onValueChange={setHapticsEnabled}
+            trackColor={{ false: colors.secondaryText, true: colors.accent }}
+          />
+        </View>
       </View>
     </View>
   );
@@ -92,4 +105,15 @@ const styles = StyleSheet.create({
   menuDescription: {
     fontSize: 16,
   },
+  toggleItem: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    padding: 24,
+    borderRadius: 16,
+  },
+  toggleText: {
+    fontSize: 18,
+    fontWeight: '600',
+  },
 });

ios/Ahap.swift

@@ -45,6 +45,16 @@ class Ahap: HybridAhapSpec {
   func destroyContinuousPlayer(playerId: String) throws {
     haptics.destroyContinuousPlayer(playerId: playerId)
   }
+  
+  // MARK: - Global Haptics Enable/Disable
+  
+  func setHapticsEnabled(enabled: Bool) throws {
+    haptics.hapticsEnabled = enabled
+  }
+  
+  func getHapticsEnabled() throws -> Bool {
+    return haptics.hapticsEnabled
+  }
 
 
   func startHaptic(events: [HapticEvent], curves: [HapticCurve]) throws {

ios/AhapUtils.swift

@@ -30,6 +30,8 @@ struct ContinuousPlayerConfig {
 
 class HapticFeedback {
     static let shared = HapticFeedback()
+    
+    private static let hapticsEnabledKey = "com.ahap.hapticsEnabled"
 
     private var engine: CHHapticEngine?
     private var hapticPlayers: [String: CHHapticAdvancedPatternPlayer] = [:]
@@ -41,6 +43,23 @@ class HapticFeedback {
     public var supportsHaptics: Bool {
         return CHHapticEngine.capabilitiesForHardware().supportsHaptics
     }
+    
+    // MARK: - Global Haptics Enable/Disable
+    
+    /// Returns whether haptics are globally enabled. Persisted in UserDefaults.
+    /// Defaults to true if not previously set.
+    public var hapticsEnabled: Bool {
+        get {
+            // If key doesn't exist, default to true (haptics enabled)
+            if UserDefaults.standard.object(forKey: HapticFeedback.hapticsEnabledKey) == nil {
+                return true
+            }
+            return UserDefaults.standard.bool(forKey: HapticFeedback.hapticsEnabledKey)
+        }
+        set {
+            UserDefaults.standard.set(newValue, forKey: HapticFeedback.hapticsEnabledKey)
+        }
+    }
 
     public func createAndStartHapticEngine() {
         guard supportsHaptics else {
@@ -175,6 +194,8 @@ class HapticFeedback {
     }
 
     public func startHapticPlayer<State: HapticAnimationState>(for state: State) {
+        guard hapticsEnabled else { return }
+        
         lock.lock()
         defer { lock.unlock() }
 
@@ -283,7 +304,10 @@ class HapticFeedback {
 
     /// Starts the continuous haptic player with the given ID.
     /// - If the player doesn't exist (not created or already destroyed), this is a safe no-op.
+    /// - If haptics are globally disabled, this is a no-op.
     public func startContinuousPlayer(playerId: String) {
+        guard hapticsEnabled else { return }
+        
         lock.lock()
         defer { lock.unlock() }
 

src/Ahap.nitro.ts

@@ -45,4 +45,7 @@ export interface Ahap
   ): void;
   stopContinuousPlayer(playerId: string): void;
   destroyContinuousPlayer(playerId: string): void;
+
+  setHapticsEnabled(enabled: boolean): void;
+  getHapticsEnabled(): boolean;
 }

src/index.tsx

@@ -1,4 +1,4 @@
-import { useEffect } from 'react';
+import { useEffect, useState, useCallback } from 'react';
 import { AppState } from 'react-native';
 import { NitroModules } from 'react-native-nitro-modules';
 import type {
@@ -94,6 +94,62 @@ export function destroyContinuousPlayer(playerId: string): void {
   return boxedAhap.unbox().destroyContinuousPlayer(playerId);
 }
 
+// MARK: - Global Haptics Enable/Disable
+
+/**
+ * Enable or disable haptics globally. This setting is persisted across app restarts.
+ * When disabled, all haptic functions become no-ops (no haptics will play).
+ * This does not affect engine initialization/destruction.
+ *
+ * @param enabled - Whether haptics should be enabled
+ */
+export function setHapticsEnabled(enabled: boolean): void {
+  'worklet';
+  return boxedAhap.unbox().setHapticsEnabled(enabled);
+}
+
+/**
+ * Get the current global haptics enabled state.
+ * Defaults to true if not previously set.
+ *
+ * @returns Whether haptics are currently enabled
+ */
+export function getHapticsEnabled(): boolean {
+  'worklet';
+  return boxedAhap.unbox().getHapticsEnabled();
+}
+
+/**
+ * Hook to manage the global haptics enabled state.
+ * Provides reactive state and a setter function.
+ *
+ * @returns [isEnabled, setEnabled] - Current state and setter function
+ *
+ * @example
+ * ```tsx
+ * function SettingsScreen() {
+ *   const [hapticsEnabled, setHapticsEnabled] = useHapticsEnabled();
+ *
+ *   return (
+ *     <Switch
+ *       value={hapticsEnabled}
+ *       onValueChange={setHapticsEnabled}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useHapticsEnabled(): [boolean, (enabled: boolean) => void] {
+  const [enabled, setEnabled] = useState(() => getHapticsEnabled());
+
+  const setHapticsEnabledState = useCallback((value: boolean) => {
+    setHapticsEnabled(value);
+    setEnabled(value);
+  }, []);
+
+  return [enabled, setHapticsEnabledState] as const;
+}
+
 /**
  * Hook to manage a continuous haptic player lifecycle.
  *