Haptics API

A low-level API for triggering haptic feedback on native platforms without React hooks.

Overview

The Haptics API provides direct access to haptic feedback functionality. Use this API when you need to trigger haptics outside of React components, such as in utility functions, callbacks, or non-React code paths.

For React components, consider using the useHaptics hook instead, which provides the same functionality with React-friendly memoization.

Import

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

Usage

Basic Example

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

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

// Trigger haptic feedback directly
trigger("light");

In Utility Functions

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

export const handlePaymentSuccess = (transaction: Transaction) => {
  trigger("success");
  // Process successful payment
};

export const handleValidationError = (errors: ValidationError[]) => {
  trigger("error");
  // Handle validation errors
};

API Reference

trigger(type: HapticFeedbackType)

Triggers haptic feedback with the specified type. Only triggers feedback if haptics are globally enabled via setHapticsEnabled(true).

Parameters:

Parameter	Type	Description
type	HapticFeedbackType	The type of haptic feedback

Returns: void

setHapticsEnabled(enabled: boolean)

Globally enables or disables haptic feedback for the entire application.

Parameters:

Parameter	Type	Description
enabled	boolean	true to enable haptics, false to disable

Returns: void

HapticFeedbackType

A TypeScript type representing valid haptic feedback types:

type HapticFeedbackType =
  | "light"
  | "medium"
  | "heavy"
  | "soft"
  | "rigid"
  | "selection"
  | "success"
  | "warning"
  | "error";

Haptic 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

When to Use

Use the Haptics API directly when:

• You need to trigger haptics outside of React components
• You're working in utility functions or service layers
• You need to trigger haptics from animation callbacks
• You want to avoid React hook overhead in performance-critical code

Use the useHaptics hook when:

• You're working within a React component
• You want memoized trigger functions for stable references
• You need the trigger function in dependency arrays

Platform Support

• ✅ iOS
• ✅ Android

Haptic feedback only works on devices that support it. The API gracefully handles unsupported devices by not triggering any feedback.

Related

• useHaptics - React hook wrapper for haptic feedback