@thesonicprint/haptics

A modern haptics library for React and Progressive Web Apps (PWA). Provides a declarative way to interact with the Vibration API with advanced patterns, pulse-width modulation (PWM), and built-in React hooks/components.

Features

- Modern ES6 Core: Lightweight and dependency-free core.
- React Ready: Full suite of hooks, context provider, and components.
- Advanced Patterns: Easily create complex tactile sequences.
- PWM Support: Fine-grained control over vibration intensity.
- PWA Optimized: Robust error handling for non-supported devices and environments.
- Recording: Record tactile patterns from user touch/mouse events.

Installation

``bash
npm install @thesonicprint/haptics
`

Quick Start

$3

`javascript
import { vibrate, clunk, notification } from '@thesonicprint/haptics';

// Simple vibration
vibrate(50);

// Built-in patterns
clunk(100);
notification(500);
`

$3

`jsx
import { HapticsProvider, useHaptics } from '@thesonicprint/haptics';

function App() {
return (



);
}

function MyComponent() {
const { clunk, fadeIn } = useHaptics();

return (
clunk(50)}>
Click Me

);
}
`

Pulse Width Modulation (PWM)

PWM allows you to simulate different vibration intensities by rapidly cycling the vibration motor on and off.

$3

`javascript
import { createPatternPWM } from '@thesonicprint/haptics';

// Intensity presets (on-duration, off-duration in ms)
const light = createPatternPWM(5, 25);
const medium = createPatternPWM(15, 15);
const strong = createPatternPWM(25, 5);

// Usage: call with total duration
light(300); // Soft vibration for 300ms
strong(500); // Intense vibration for 500ms
`

$3

- isSupported: Use this flag to conditionally show/hide haptic settings or UI elements.
- Silent Fail: Calling vibration methods on unsupported devices will not throw errors; they will return false or return silently.

`javascript
import { enabled } from '@thesonicprint/haptics';

if (enabled) {
console.log("Haptics are supported and ready!");
}
`

API Reference

$3

| Method | Description |
| :--- | :--- |
| vibrate(pattern) | Standard vibration. Pattern can be a number or number[]. |
| record() | Start recording a pattern from touch/mouse events. |
| finish() | Stop recording and return the pattern as an array. |
| pwm(duration, on, off) | Raw PWM vibration for intensity control. |
| createPattern(...args) | Compose higher-order pattern functions. |
| createPatternPWM(on, off) | Factory for reusable intensity-based patterns. |

$3

All built-in effects are factory-prepared. You can call them with a total duration.

- fadeIn(duration): Gradual increase in intensity.
- fadeOut(duration): Gradual decrease in intensity.
- notification(duration): Triple-pulse "alert" pattern.
- heartbeat(duration): Double-pulse "lub-dub" sensation.
- clunk(duration): Sharp, heavy mechanical "click".

$3

The library provides fully integrated hooks and components for React/Vite projects.

- useHaptics(): Access all core haptic methods with context awareness.
- useHapticFeedback(pattern, options): Declarative hook for triggering patterns based on state.
- useHapticRecorder(): Recording interface with built-in playback and state management.
- , , : Specialized UI components with built-in tactile feedback.

---

Creative Implementations

$3

`javascript
import { createPattern } from '@thesonicprint/haptics';

const MORSE_MAP = {
'.': [100, 100], // Dot + pause
'-': [300, 100], // Dash + pause
' ': [0, 400] // Word gap
};

function textToMorse(text) {
const pattern = text.toLowerCase().split('').flatMap(char => {
if (char === ' ') return MORSE_MAP[' '];
return MORSE_MAP[char] || [];
});
return createPattern(pattern);
}

const sos = textToMorse('sos');
sos(1000); // Triggers tactile SOS (scaled to 1s)
`

$3

`javascript
import { fadeIn, clunk } from '@thesonicprint/haptics';

async function simulateScan() {
// Start with a 1s "scanning" ramp up
fadeIn(1000);

await new Promise(r => setTimeout(r, 1100));

// Confirmed hit
clunk(100);
}
`

$3

`javascript
import { createPatternPWM } from '@sonicprint/haptics';

// High frequency (Smooth/Metallic)
const metallic = createPatternPWM(2, 2);
// Low frequency (Rough/Gravel)
const rough = createPatternPWM(30, 30);

// Usage in interaction


`javascript
import { vibrate } from '@thesonicprint/haptics';

function onCollision(velocity) {
// Scale duration (10ms to 200ms) based on impact speed
const duration = Math.min(Math.max(velocity * 10, 10), 200);
vibrate(duration);
}
``

License

MIT © Sonicprint