Modern haptics library for React and PWA
npm install @thesonicprint/hapticsA 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.
- 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.
``bash`
npm install @thesonicprint/haptics
`javascript
import { vibrate, clunk, notification } from '@thesonicprint/haptics';
// Simple vibration
vibrate(50);
// Built-in patterns
clunk(100);
notification(500);
`
`jsx
import { HapticsProvider, useHaptics } from '@thesonicprint/haptics';
function App() {
return (
);
}
function MyComponent() {
const { clunk, fadeIn } = useHaptics();
return (
);
}
`
PWM allows you to simulate different vibration intensities by rapidly cycling the vibration motor on and off.
`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
`
The library is designed to fail silently on unsupported devices (like desktop browsers or iOS Safari).
- 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!");
}
`
| 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. |
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".
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.
---
`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)
`
`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);
}
`
`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
$3
Scale haptic feedback based on game physics or interaction speed.`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);
}
``MIT © Sonicprint