Treehouse

Vibration API

By on  

Many of the new APIs provided to us by browser vendors are more targeted toward the mobile user than the desktop user.  One of those simple APIs the Vibration API.  The Vibration API allows developers to direct the device, using JavaScript, to vibrate in a pattern for a given duration.

Detecting Vibration API Support

It's always good to check for the presence of API support before using it;  here's how you can detect the Vibration API's presence:

// Standards ftw!
var supportsVibrate = "vibrate" in navigator;

The Vibration API consists of only one method provided to the window.navigator object:  vibrate.

Vibration API Basics

The navigator.vibrate function accepts either a single number or an array of numbers for a series of vibrations. When using the array method, the even indices represent vibration duration, the odd indices represent a delay before the next vibration.

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

// Vibrate multiple times for multiple durations
// Vibrate for three seconds, wait two seconds, then vibrate for one second
navigator.vibrate([3000, 2000, 1000]);

To stop vibration when active, simply pass a 0 or an empty array to the navigator.vibrate method:

// Either of these stop vibration
navigator.vibrate(0);
navigator.vibrate([]);

Realize that vibrations do not loop until stopped with 0 or an empty array;  the single number vibration occurs once and then becomes silent, the array of vibration durations run and becomes silent again.

Continued Vibration

Some basic setInterval and clearInterval action will allow us you to create persistent vibration:

var vibrateInterval;

// Starts vibration at passed in level
function startVibrate(duration) {
	navigator.vibrate(duration);
}

// Stops vibration
function stopVibrate() {
	// Clear interval and stop persistent vibrating 
	if(vibrateInterval) clearInterval(vibrateInterval);
	navigator.vibrate(0);
}

// Start persistent vibration at given duration and interval
// Assumes a number value is given
function startPeristentVibrate(duration, interval) {
	vibrateInterval = setInterval(function() {
		startVibrate(duration);
	}, interval);
}

Of course the snippet above doesn't take into account the array method of vibration;  persistent array-based vibration will require calculating the sum of the array items and creating an interval based on that number (with an additional delay, probably).

Why Use the Vibration API?

This API is clearly targeted toward mobile devices.  The Vibration API would be good for alerts within mobile web applications, and would be especially awesome when used in games or media-heavy applications.  Imagine watching a video on your mobile device, and during an explosion scene, your phone got a bit of a shake.  Or playing Bomberman and feeling a gentle kick when a block explodes!

What do you think of the Vibration API:  immediately useful or not quite yet?

At the time of writing, Firefox BETA for Android is the only browser which supports the Vibration API. WebKit landed the Vibration API a while back, but in my testing of iOS Chrome and Safari, as well as Android Chrome and standard browser, I could not find a working vibration property. Opera doesn't appear to support vibration yet either.

ydkjs-5.png

Recent Features

  • Send Text Messages with PHP

    Kids these days, I tell ya.  All they care about is the technology.  The video games.  The bottled water.  Oh, and the texting, always the texting.  Back in my day, all we had was...OK, I had all of these things...

  • CSS Animations Between Media Queries

    CSS animations are right up there with sliced bread. CSS animations are efficient because they can be hardware accelerated, they require no JavaScript overhead, and they are composed of very little CSS code. Quite often we add CSS...

  • 5 More HTML5 APIs You Didnât Know Existed

    The HTML5 revolution has provided us some awesome JavaScript and HTML APIs.  Some are APIs we knew we've needed for years, others are cutting edge mobile and desktop helpers.  Regardless of API strength or purpose, anything to help us...

Incredible Demos

  • MooTools OpenLinks Class – Updated

    A long time back I coded a MooTools class called OpenLinks. The class is quite useful but the code...sucks. I've gotten much better with MooTools over the past years so I thought I'd go back and update...

  • Image Reflections with CSS

    Image reflection is a great way to subtly spice up an image.  The first method of creating these reflections was baking them right into the images themselves.  Within the past few years, we've introduced JavaScript strategies and CANVAS...

  • Facebook Open Graph META Tags

    It's no secret that Facebook has become a major traffic driver for all types of websites.  Nowadays even large corporations steer consumers toward their Facebook pages instead of the corporate websites directly.  And of course there are Facebook "Like" and...

Discussion

  1. Great article, appreciate the code samples. I think this could be great if it’s widely supported and used properly. I’d like to see mobile browsers add an option to turn it off, like you can with location services. It could be very annoying if a website is constantly buzzing at me.

  2. @Steve Edson I don’t believe it should need to ask. If it’s annoying just close the site. I tested it and it won’t run in the background if Firefox isn’t the focused application.

    I know where you’re coming from w/ it being annoying, but it’s the same w/ popups, popunders, blink, css3 animations, etc… if you don’t like it, close it and blame the developer for using it improperly. :)

    • Good point Andrew. Features that are more invasive, like Geolocation and getUserMedia, do require permission via prompt; vibration isn’t invasive but could be misused. That said, browsers do provide popup blocking so…who knows. I wouldn’t be opposed to the Vibration API being a setting.

  3. Hey Dave,

    Nice write-up!

    Speaking of standards, shouldn’t the sniff for “vibrate” look more like the following?

    // Standards ftw!
    var supportsVibrate = "vibrate" in (clientInformation || navigator);
    

    Regards,

    – John

  4. Chris Strat

    That is brilliant – I am loving how there are API expanding deeper into the device.

    One that I am really keen on finding is one to prevent the screen from dimming/locking.
    Are you aware of any that are out there that work across iPhone and Android browsers?

  5. Rick

    Next thing I want to see is desktop browsers providing support for these things.

    Vibrate, for example, could make the tab jiggle. Or play a fake vibrate noise.

  6. “Make the tab jiggle” !? Please God no ! A persistent animation was annoying enough, imagine shaking all the content of a tab.
    I think it can be well used on a mobile : i once developed a site where alert windows could be critical (a one-cent bidding playful website), and buzzing could have been a real plus on mobiles.

  7. Alex

    Maybe pr0n companies will adopt this “new technology” faster than the rest of us… AGAIN :P

  8. psobko

    I really hope this never comes to my iPhone. Apple’s had a history of cracking down on apps that abuse vibration, in fact it’s even impossible to create a sustained vibration with the iOS SDK. The last thing we need is unregulated access to this feature. The less hardware the browser has access to, the better.

  9. Ravindran

    I hope user should get some say/allow on whether he should allow the site to use vibrate API. (similar to desktop notification API in Chrome desktop browser)

    In desktop era, SetForegroundWindow (http://msdn.microsoft.com/en-us/library/windows/desktop/ms633539(v=vs.85).aspx) is the most abused API by desktop applications. Eventually Microsoft changed the behavior to just flash the taskbar entry.

  10. I really love the MSN nudge idea: http://dev.ih8.nl/demos/vibrate/ No, really! We need more bling

  11. Bart Nelis

    Thanks for this article, this could prove very useful indeed !

  12. Bart Nelis

    Very interesting feature, thx for the article. This could prove very useful .

  13. The Vibration API is still primarily unsupported.

  14. You should put “WARNING: ONLY WORKS FOR FIREFOX BROWSER” at the top of this page.

  15. alexandervrs

    Is this designed to work along with the Gamepad API to enable vibration support for gamepads or is this mobile device only?

Wrap your code in <pre class="{language}"></pre> tags, link to a GitHub gist, JSFiddle fiddle, or CodePen pen to embed!

Use Code Editor