The Vibration API in HTML5 with JavaScript

HTML5 has been a great evolution for the web; it incorporates all types of elements that we can use for multiple purposes and extend through various libraries. Creating interactive websites has been greatly simplified, thereby improving the user experience on PC and mobile devices.

One example of a utility that is very little used and less exploited is the Vibration API in HTML. This is a very useful API for mobile applications today. Receiving emails, text messages, calls—all of this involves a device vibration, which is the first thing we notice if we carry our smartphone, and it's one of the few APIs that doesn't use sight or our fingers. It's enough that we have the mobile device nearby and it vibrates; in this way, the application gives us information about something (generally a notification alert) without the need to look at the mobile, and we can transmit all of this to the user.

Devices like tablets and phones have a significant presence on the web today. It is estimated that the data traffic generated by these devices will surpass the data traffic generated by PCs in a few years. For this reason, it is important for us developers to exploit all the tools the Web provides in the best possible way; among them is the HTML5 Vibration API. In this article, we will see how to add this feature of making devices vibrate to our applications.

The vibrate method of the navigator object allows the activation of a device's hardware vibration using JavaScript. Of course, this will only happen if such hardware is present on said device. If the device does not support vibration, the method will have no effect on the device.

What is it? The Vibration API in detail

If there's one HTML5 API that has always seemed powerful, underestimated, and surprisingly little exploited to me, it's the Vibration API. In a world where mobile traffic surpasses PC traffic and where the user has their phone on them almost all day, being able to send a signal without relying on sight or sound is pure gold. More than once, while developing, I've noticed that vibration is the first thing the user perceives even with the screen off, so ignoring it is losing an opportunity to improve the experience.

And that's because vibration is one of those ways of transmitting information that is not through the eyes but through touch, in which you can give the user a warning or feedback.

Accessibility and UX improvements

Vibration is especially useful when:

• The user cannot look at the screen.
• You need to reinforce an action (like a "physical click").
• You want to offer feedback for users with visual impairments.

Recommendations:

• Short vibrations: 30–200 ms
• Do not repeat patterns too many times
• Offer a switch to turn it off

As we indicated before, the Vibration API is designed so that instead of receiving a tactile or sonic response, this response is physical, since the device has the capacity to vibrate on a modern Android, iOS, or similar device.

The Vibration API (HTML5 Vibration API) allows you to activate the haptic engine of a mobile device from JavaScript. That means your web application can emit tactile vibrations in response to actions, notifications, alerts, or any important change.

Why is it used so little if it's so useful?

Primarily for three reasons:

• Many developers don't even know it exists.
• Some platforms (like iOS) limit its use.
• There's a fear of "bothering" the user (and rightly so if used incorrectly).

Even so, on Android mobiles — and in the vast majority of Chromium-based browsers — it works very well, and it is extremely easy to use.

How to use it navigator.vibrate()? - Syntax

The Vibration API is accessed through the global navigator object in the following way:

navigator.vibrate(pattern);

Vibrate a single time

Where pattern can be:

• An unsigned integer: Which represents the duration given in milliseconds of one and only one vibration; therefore, it is the simplest way to set up vibrations; let's see an example: // vibrates for one second navigator.vibrate(1000);

The code above will make the device vibrate for 1000 milliseconds, or what is the same, for one second.

navigator.vibrate(1000); // vibrates 1 second

Vibrate/stop vibrating multiple times

• A sequence of signed integers: or rather, an array with multiple values that represent the alternating vibration and pause intervals in milliseconds for each of the values contained within the array. // vibrates for one second, stops vibrating for half a second, then vibrates for two more seconds navigator.vibrate([1000, 500, 2000]);

The code above will make the device vibrate for one second, then there will be a wait of half a second, to finish with a vibration of two seconds.

Stopping or pausing device vibration

The Vibration API will not block your JavaScript code; and therefore, it will continue to execute while the device is vibrating. If for some circumstance you wish to end the vibration, you can set the pattern to zero:

// stops device vibration navigator.vibrate(0);

It is also possible to cancel device vibration with:

// also stops device vibration navigator.vibrate([]); 
// this also... navigator.vibrate([0]);

Vibration patterns (arrays)

If you want to vibrate → pause → vibrate → pause, use an array of times:

navigator.vibrate([1000, 500, 2000]);

This vibrates 1s, pauses 0.5s, and vibrates 2s.

How to stop vibration correctly

There are several ways to stop:

navigator.vibrate(0); navigator.vibrate([]); 
navigator.vibrate([0]);

Detecting Vibration API support in browsers

It is always advisable to perform the necessary validations before working with any of the HTML5 APIs; to detect the presence of the Vibration API, you only have to perform the following check:

var supportVibration= "vibrate" in navigator;

Or more modern:

const hasVibration = "vibrate" in navigator;

Image 1: Support for the Vibration API in the Google Chrome browser for PC.

As we can see in the image above; this check will return a boolean:

• true: The browser offers support for the Vibration API.
• false: The browser does not offer support for the Vibration API.

Behavior on PCs, tablets, and iOS

Over the years, in my tests I have seen that:

• On PCs, it always returns true, but they obviously don't vibrate.
• Android Tablet: fully functional vibration.
• iOS: very limited; it doesn't work in most browsers (Safari usually doesn't allow it).

So this check prevents surprises:

if (navigator.vibrate) { 
   navigator.vibrate(200); 
} else { 
   console.log("This device does not support vibration."); 
}

What to use the Vibration API for?

This API is clearly designed for mobile devices; it is helpful for alerting the user about a change in the Web application; even while developing, for making the device vibrate during an explosion or a gunfight.

This is where this API shines. In fact, when I was working with mobile notifications, I realized that vibration is the best way to alert the user without them looking at the screen.

Alerts and notifications

Perfect for:

• Incoming messages
• Important status changes
• Critical errors
• Reminders

I really like combining it with Web Notifications:

navigator.vibrate([200, 100, 200]);

Interactive events (games, explosions, shots, feedback)

In web games, a simple vibration completely changes the experience.

When I made a prototype with shots and explosions, short vibrations worked great:

navigator.vibrate([50, 30, 100]);

Current limitations and important considerations

Privacy and permissions

In some browsers, vibration is only allowed:

• In secure contexts (HTTPS)
• After a user interaction (previous click or tap) 

Conclusions

This API is very simple to use and very powerful, as it allows access to the device's hardware; however, you have to be very careful when using this API. It should be remembered that it only works with mobile devices (obviously the PC is not going to vibrate), in addition to this, we should NOT leave the client's device vibrating eternally, however provocative and fun the idea may seem.

The Vibration API is simple, useful, and tremendously undervalued. It allows you to access the device's hardware without complications and adds a layer of tactile interaction that many users appreciate.

As always when working with hardware APIs, I check for support, take care of the duration, and avoid abuse. But when used well, it can turn a normal web app into a much more immersive experience.

Frequently Asked Questions about the Vibration API

• Does it work on iOS / iPhone?
  • In most cases, no. Apple heavily limits this API.
• Does it need HTTPS?
  • In most modern browsers, yes.
• Can I combine it with push notifications?
  • Yes, it works wonderfully.
• Why doesn't my mobile vibrate even though I call navigator.vibrate()?
  • Because the hardware does not allow it, the browser does not support it, or there was no previous user interaction.