How to Use the HTML5 Vibration API

Contributing Editor

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.

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • Design by Adrian

    I don’t dig sending an array. What if you want vibrate-vibrate-wait-vibrate? There’s no way of telling. Chaining would be better:

    navigator.vibrate(500,0).vibrate(100.0).vibrate(500,100)

    (vibrate for 500ms, then shorter 200ms, then wait 100ms before vibrating for 500ms again)

    Of course, you could add zeroes as 0 wait time… navigator.vibrate([500,0,200,100,500])…

    • Etienne

      Maybe something I don’t understand… but if you want to vibrate for 500, then 200, then wait 100 then vibrate 500, that is pretty much the exact same thing as vibrate 700 (500+200), wait 100, vibrate 500… so the array method would work.

    • Will Boyd

      vibrate vibrate wait vibrate == viiiiiiibrate wait vibrate. 0 ms wait time would just mean the 2 vibrations are continuous as one.

      I do see another drawback to the array input though. How would you specify intensity? It’s not hard to imagine devices being capable of varying intensity vibrations.

      • Craig Buckler

        Intensity would be a great setting – especially for games. You can envisage the vibration API being used in HTML5 games on game controllers for the Xbox One and PS4.

    • ChadF

      Maybe there should be a string pattern allowed, in a form similar to GW-BASIC’s PLAY command that was used to play music/sounds from the internal PC speaker, back in the day. Then rather complex styles (and even frequencies, where support by the device) could easily be done.

  • Scott

    Cool the new BLINK “tag” for HTML5! ;D

    • ChadF

      I don’t know.. the blink tag didn’t seem to do much but be annoying.

      But this new HTML feature could launch a new area of service on sites serving adult content. ;)

  • swampwiz

    I am old vibroacoustics engineer. I wonder if the API allows for a different level of amplitude or frequency.

    • Craig Buckler

      Not currently. Also, even if it were available, I suspect it would vary considerably between devices so I’m not sure it’d be useful.

  • Spoek1

    This is awesome for games! Looking forward to try it when ios starts supporting it.

  • salsero69

    Let’s play the which web page in which tab is vibrating my device?

  • http://rachelnabors.com Rachel Nabors

    I can immediately think of a legitimate use for this API: “personal massager” HTML5 apps.