@luxonauta/use-vibration

useVibration

A React hook for controlling device vibration.

Why should we use more haptic feedback on the web? Please read about it here.

Installation

npm install @luxonauta/use-vibration

Basic Usage

import useVibration, { VibrationPatterns } from "@luxonauta/use-vibration";

export const Component = () => {
  const [{ isSupported, isVibrating }, { vibrate, stop }] = useVibration();

  if (!isSupported) {
    return <p>Vibration not supported on your device</p>;
  }

  return (
    <>
      <button
        type="button"
        onClick={() => vibrate(VibrationPatterns.tap)}
        disabled={isVibrating}
      >
        {isVibrating ? "Vibrating" : "Tap me for haptic feedback"}
      </button>
      {isVibrating && (
        <button type="button" onClick={stop}>
          Stop Vibration
        </button>
      )}
    </>
  );
};

API Reference

Hook Return Values

const [state, controls] = useVibration();

State Object

Property	Type	Description
isSupported	boolean	Whether the device supports vibration
isVibrating	boolean	Whether the device is currently vibrating

Controls Object

Method	Type	Description
vibrate	(pattern?: VibrationPattern) => void	Triggers vibration with an optional pattern
stop	() => void	Stops any ongoing vibration

Types

// Single duration or pattern array
type VibrationPattern = number | number[];

Predefined Patterns

The hook comes with common vibration patterns for different interactions:

Pattern	Description	Value
tap	Subtle feedback	100
standard	Standard vibration	200
heavy	Emphasis	500
double	Double-tap pattern	[100, 30, 100]
triple	Triple-tap pattern	[100, 30, 100, 30, 100]
success	Success feedback	[100, 50, 200]
error	Error or warning	[300, 100, 500]
notification	For notifications	[200, 100, 100]
sos	SOS in morse code	[100, 100, 100, 100, 100, 100, 300, 100, 300, 100, 300, 100, 100, 100, 100, 100, 100]
heartbeat	Heartbeat simulation	[100, 100, 100, 400]

Advanced Usage

Custom Patterns

You can create custom vibration patterns using arrays where:

• Even-indexed elements (0, 2, 4, ...) specify vibration durations;
• Odd-indexed elements (1, 3, 5, ...) specify pause durations.

// Pattern: vibrate 200ms → pause 100ms → vibrate 400ms → pause 100ms → vibrate 200ms
const customPattern = [200, 100, 400, 100, 200];
vibrate(customPattern);

Creating UI Feedback

const FeedbackApp = () => {
  const [, { vibrate }] = useVibration();

  const handleSuccess = () => {
    // Haptic feedback
    vibrate(VibrationPatterns.success);
    // Visual feedback
    setStatus("Success!");
  };

  const handleError = () => {
    // Haptic feedback
    vibrate(VibrationPatterns.error);
    // Visual feedback
    setStatus("Error!");
  };

  // App
};

Game Example

const Game = () => {
  const [, { vibrate }] = useVibration();

  const handleCollision = (intensity) => {
    // Adjust the vibration based on collision intensity
    const duration = Math.min(Math.round(intensity * 300), 1000);
    vibrate(duration);
  };

  // Game
};

Browser Compatibility

The Vibration API is supported across most modern browsers:

Desktop Browsers

• Chrome: 32+;
• Edge: 79+;
• Opera: 19+;
• Firefox: Not supported;
• Safari: Not supported.

Mobile Browsers

• Chrome for Android: 32+;
• Firefox for Android: 79+;
• Opera for Android: 19+;
• Samsung Internet: 2.0+;
• "WebView Android": 4.4.3+;
• Safari iOS: Not supported.

Important Notes

• The Vibration API is primarily designed for mobile devices;
• Desktop browsers may support the API, but won't produce actual vibration.

Recommendation: Always check isSupported before using vibration features in your app.

Best Practices

• Always check support first

  const [{ isSupported }] = useVibration();
  if (!isSupported) return <AlternativeFeedback />;
  

• Use sparingly

  • Excessive vibration can be annoying and drain battery. Use only for important feedback.

• Respect user preferences

  • Consider adding a setting to disable vibration.

• Provide alternatives

  • Always pair vibration with visual feedback for accessibility.

• Keep patterns simple

  • Complex patterns may not work consistently across devices.

Limitations

• Some Android devices may ignore pattern details and use their default vibration;
• Vibration might not work when browser is in background.

License

MIT