useHaptics

A React hook that provides haptic feedback functionality for user interactions on native platforms.

Overview

The useHaptics hook returns a memoized object with a trigger function that provides tactile feedback to users when they interact with components. Haptic feedback is disabled by default and must be explicitly enabled using the setHapticsEnabled function.

This hook is a thin wrapper around the Haptics API. For usage outside of React components, import the API directly.

Import

import { useHaptics } from "@ppb/the-wall-native/hooks/useHaptics";

Usage

Basic Example

import { useHaptics } from "@ppb/the-wall-native/hooks/useHaptics";

const MyComponent = () => {
  const haptics = useHaptics();

  const handlePress = () => {
    haptics.trigger("light");
    // Handle press logic
  };

  return <Button onPress={handlePress}>Press Me</Button>;
};

Enabling Haptics Globally

Haptic feedback is disabled by default. You must enable it before it will work:

import { setHapticsEnabled } from "@ppb/the-wall-native/api/haptics";

// Enable haptics globally (typically in app initialization)
setHapticsEnabled(true);

// Disable haptics globally
setHapticsEnabled(false);

Different Haptic Types

import { useHaptics } from "@ppb/the-wall-native/hooks/useHaptics";

const InteractiveComponent = () => {
  const haptics = useHaptics();

  return (
    <>
      <Button onPress={() => haptics.trigger("light")}>Light Impact</Button>
      <Button onPress={() => haptics.trigger("medium")}>Medium Impact</Button>
      <Button onPress={() => haptics.trigger("heavy")}>Heavy Impact</Button>
      <Button onPress={() => haptics.trigger("selection")}>Selection</Button>
      <Button onPress={() => haptics.trigger("success")}>Success</Button>
      <Button onPress={() => haptics.trigger("warning")}>Warning</Button>
      <Button onPress={() => haptics.trigger("error")}>Error</Button>
    </>
  );
};

API

useHaptics()

Returns a memoized object with haptic feedback functionality.

Returns:

{
  trigger: (type: HapticFeedbackType) => void
}

Haptic Types

The trigger function accepts the following haptic feedback types:

Type	Description	Use Case
"light"	Light impact feedback	Button taps, simple interactions
"medium"	Medium impact feedback	More significant interactions
"heavy"	Heavy impact feedback	Important or impactful actions
"soft"	Soft impact feedback	Gentle, subtle interactions
"rigid"	Rigid impact feedback	Firm, precise interactions
"selection"	Selection feedback	Toggle switches, picker selections
"success"	Success notification	Successful actions or confirmations
"warning"	Warning notification	Warning states or cautionary actions
"error"	Error notification	Error states or failed actions

Best Practices

1. Enable Haptics Early: Call setHapticsEnabled(true) during app initialization if haptic feedback should be available throughout the app.

2. Use Appropriate Types: Choose the haptic type that matches the interaction:

   • Use "light" for most button presses and taps
   • Use "selection" for toggles and pickers
   • Use "success", "warning", or "error" for feedback notifications

3. Don't Overuse: Only trigger haptics for meaningful interactions. Too much haptic feedback can be overwhelming.

4. Respect User Preferences: Consider allowing users to disable haptics in your app settings by calling setHapticsEnabled(false).

5. Consistent Usage: Use the same haptic type for similar interactions across your app for consistency.

Examples

ActionButton with Haptic Feedback

import { useCallback } from "react";
import { TouchableHighlight } from "react-native";
import { useHaptics } from "@ppb/the-wall-native/hooks/useHaptics";

const ActionButton = ({ onTap, children }) => {
  const haptics = useHaptics();

  const handleOnPressIn = useCallback(() => {
    haptics.trigger("light");
  }, [haptics]);

  return (
    <TouchableHighlight onPressIn={handleOnPressIn} onPress={onTap}>
      {children}
    </TouchableHighlight>
  );
};

Switch with Selection Feedback

import { useCallback } from "react";
import { Pressable } from "react-native";
import { useHaptics } from "@ppb/the-wall-native/hooks/useHaptics";

const Switch = ({ isChecked, onChange }) => {
  const haptics = useHaptics();

  const handleOnPressIn = useCallback(() => {
    haptics.trigger("selection");
  }, [haptics]);

  const handleOnChange = useCallback(() => {
    onChange(!isChecked);
  }, [isChecked, onChange]);

  return (
    <Pressable onPressIn={handleOnPressIn} onPress={handleOnChange}>
      {/* Switch UI */}
    </Pressable>
  );
};

Form Submission with Feedback

import { useState } from "react";
import { useHaptics } from "@ppb/the-wall-native/hooks/useHaptics";

const FormComponent = () => {
  const haptics = useHaptics();
  const [isSubmitting, setIsSubmitting] = useState(false);

  const handleSubmit = async () => {
    setIsSubmitting(true);

    try {
      await submitForm();
      haptics.trigger("success");
      // Show success message
    } catch (error) {
      haptics.trigger("error");
      // Show error message
    } finally {
      setIsSubmitting(false);
    }
  };

  return <Form onSubmit={handleSubmit} />;
};

Platform Support

• ✅ iOS
• ✅ Android

Haptic feedback will only work on devices that support it. The hook will gracefully handle unsupported devices by simply not triggering any feedback.

Related

• Haptics API - Low-level API for non-React usage

Notes

• Haptic feedback is disabled by default for performance and battery considerations
• The hook returns a memoized object, so it's safe to include in dependency arrays
• Haptics will only trigger when enabled globally via setHapticsEnabled(true)
• The abstracted types (light, medium, etc.) map to underlying platform-specific implementations