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

What is the HTML5 Vibration API?

The HTML5 Vibration API is a powerful tool that allows developers to programmatically access the vibration hardware, if it exists, on a device. This can be used to provide tactile feedback to users in response to various events, such as receiving a notification or pressing a button. It’s important to note that the API doesn’t guarantee that the vibration will occur, as the final decision is left to the operating system and the user’s settings.

How can I use the Vibration API in my web application?

To use the Vibration API, you need to call the navigator.vibrate() method. This method accepts either a single integer or an array of integers. A single integer represents the number of milliseconds the vibration should last. An array of integers represents a pattern of vibrations and pauses. For example, navigator.vibrate(200) will vibrate the device for 200 milliseconds, while navigator.vibrate([200, 100, 200]) will vibrate the device for 200 milliseconds, pause for 100 milliseconds, and then vibrate again for 200 milliseconds.

Can I use the Vibration API on all devices?

The Vibration API is primarily intended for mobile devices that have a built-in vibration hardware. However, the API can be called on any device. If the device doesn’t support vibration, the call to navigator.vibrate() will simply be ignored.

How can I check if a device supports the Vibration API?

You can check if a device supports the Vibration API by using the vibrate property of the navigator object. If the property exists, the device supports the API. Here’s how you can do it: if ("vibrate" in navigator) { /* The device supports vibration */ }.

Can I stop the vibration before it finishes?

Yes, you can stop the vibration before it finishes by calling the navigator.vibrate() method with a parameter of 0 or an empty array. For example, navigator.vibrate(0) or navigator.vibrate([]).

Is the Vibration API supported by all browsers?

The Vibration API is supported by most modern browsers, including Chrome, Firefox, and Opera. However, it’s not supported by Internet Explorer, and the support in Safari is limited.

Can I use the Vibration API in a worker context?

No, the Vibration API is not available in a worker context. It can only be used in the main browsing context.

Are there any restrictions on the use of the Vibration API?

Yes, there are some restrictions on the use of the Vibration API. For example, in some browsers, the API can only be used in response to a user action, such as a click or a touch, to prevent abusive or annoying usage.

Can I specify the intensity of the vibration?

No, the Vibration API doesn’t allow you to specify the intensity of the vibration. The intensity is controlled by the device’s hardware and the operating system.

Can I use the Vibration API to create complex vibration patterns?

Yes, you can use the Vibration API to create complex vibration patterns by passing an array of integers to the navigator.vibrate() method. Each integer in the array represents the duration of a vibration or a pause. For example, navigator.vibrate([200, 100, 200, 100, 200]) will create a pattern of three vibrations, each 200 milliseconds long, separated by two pauses, each 100 milliseconds long.