Vibration Api

The previous chapter covered APIs that reach out to external hardware. This one is about the device itself reporting back -- and the smallest example of that is making the phone buzz.

The entire Vibration API is one function:

That is it. No permission dialog, no event listener, no object to manage.

Single and Pattern

A number vibrates for that many milliseconds:

An array alternates between vibrate and pause, starting with vibrate:

The array position determines the meaning. Even indices (0, 2, 4) are vibration durations. Odd indices (1, 3) are pause durations. The pattern ends after the last value.

To stop an ongoing vibration early:

Either call cancels a running pattern immediately.

Where It Fits

Vibration is a feedback channel. The best uses are confirmation moments and alerts that cannot rely on sound:

• Confirm a form submission was accepted
• Punctuate a game event (enemy hit, timer expired)
• Alert that a background task finished while the user was doing something else
• Pair with the Screen Wake Lock pattern: keep the screen on and vibrate when a cooking timer finishes

Do not vibrate without user intent. A page that vibrates on load or during passive browsing is hostile. Match vibration to actions the user explicitly triggered.

ExpandVibration API: single vs pattern, the alternating vibrate/pause array, and support

Return Value

navigator.vibrate() returns true if the call was accepted and false if the device does not support vibration or if vibration is disabled by the user. It does not tell you when the vibration finishes -- there is no callback or promise.

Support

The Vibration API is narrow-band. Chrome on Android and Samsung Internet support it. Desktop browsers accept the call (no error) but do nothing -- there is no vibration hardware. iOS Safari does not support it.

Vibration gives you one bit of feedback -- buzz or no buzz. The Battery Status API gives you a more detailed view of device state: exactly how much power is left and whether the cable is connected.

The Essentials

1. navigator.vibrate(n) -- vibrate for n milliseconds. No permission needed.
2. navigator.vibrate([v, p, v, p, ...]) -- pattern where even indices vibrate, odd indices pause, all in milliseconds.
3. navigator.vibrate(0) or navigator.vibrate([]) -- cancel immediately.
4. Returns true if accepted, false if unsupported. No callback or promise -- no way to know when it finishes.
5. Chrome on Android only in practice. Desktop browsers accept the call silently. iOS does not support it.

Further Reading and Watching

• HTML5 Vibration API (YouTube) -- Steve Griffith covers single vibration, patterns, and cancellation with working browser examples
• Vibration API -- MDN -- reference for the pattern spec, return value behavior, and browser support table