How to Use the HTML5 Vibration API

Users are increasingly using smartphones and tablets to access the web. As of December 2013, one in every five web visits is from a mobile device. If your website or app is mobile-aware, that figure could be far higher. Development for multiple devices has its challenges, but there are also possibilities which aren’t typically available on desktop PCs. Consider the vibration mechanism; it’s a simple tactile feedback device which can alert you of new messages or phone calls. It’s especially useful in a noisy environment where sound cannot be heard or quiet places where it would be a distraction. Wouldn’t it be great if you could use vibration in your application?…

• Walking directions could be indicated using one vibration for left, two for right.
• The phone could vibrate in a certain way when an event occurs or you’re close to someone.
• You could send secret messages in vibration-based morse code!
• A game could be enhanced by vibrating when you crash or are hit by a missile.

That’s exactly what the HTML5 Vibration API allows you to do!

To Vibrate or Not to Vibrate?

Just because we can vibrate the phone, it doesn’t follow that we should. Vibration is a huge battery drain so it’s probably best disabled if power is running low or a game is not active in the current tab. Depending on your application, it may be best to provide a user option so they can enable, disable or configure vibration criteria.

Browser Support and Detection

The API is relatively new and support is currently limited to recent versions of Firefox and Chrome. Earlier editions require moz and webkit prefixes respectively. You should also use a device which has a vibration mechanism — the API may be available in your browser, but you won’t know its working without one! Use the following check to detect for vibration support:

if ("vibrate" in navigator) {
	// vibration API supported
}

To check and use prefixed versions, you can use code such as:

// enable vibration support
navigator.vibrate = navigator.vibrate || navigator.webkitVibrate || navigator.mozVibrate || navigator.msVibrate;

if (navigator.vibrate) {
	// vibration API supported
}

Vibration Basics

A basic vibration can be set by passing a number of milliseconds to navigator.vibrate:

// vibrate for one second
navigator.vibrate(1000);

Alternatively, you can pass an array with vibration and delay parameters specified in milliseconds. For example, to vibrate for 500ms, wait for 300ms, then vibrate again for 100ms:

// vibrate for one second
navigator.vibrate([500, 300, 100]);

The even-numbered array items define a vibration time (arrays are zero-based so the first and third items are 0 and 2). Odd-numbered array items define the delay time. Vibration is non-blocking; your JavaScript code will continue to run while the device is vibrating. To stop it, you can pass zero to navigator.vibrate. This concept could be useful in games. For example, when the user crashes their car, you set navigator.vibrate(10000). However, if the crash effect ends before 10 seconds has elapsed, you set navigator.vibrate(0) to finish it.

Vibration Demonstration

To test the API in your device… View the Vibration API demonstration… View the source for all HTML, CSS and JavaScript. The form parameters build an array which is passed to navigator.vibrate when START is clicked. When the STOP button is clicked, navigator.vibrate(0); is executed. Have fun with the Vibration API and let me know if you have any interesting uses for it.

Frequently Asked Questions (FAQs) about HTML5 Vibration API