Haptics.js

Deliver vibrations on the web.

Haptics.js is a simple JavaScript library that allows you to implement vibrotactile effects using the HTML5 implementation of navigator.vibrate. In addition to providing a cross-browser compatibility layer, Haptics.js allows you to quickly create different vibrotactile effects, including fading vibrations, heartbeats, notifications, and error alerts.

Where can you use Haptics.js?

Haptics.js can be added to any web page to provide enhanced interactivity and a more interesting user interface. Haptics.js is great for:

• Adding vibrotactile feedback to games written in HTML5
• Providing vibration notifications in an HTML5 web application
• Delivering tactile responses for on-page buttons
• Creating a richer layer of interactivity in media (e.g. providing tactile sensations along with audio and video)

Open Source License

Haptics.js is available under the MIT License, and can be used and redistributed freely. If you make improvements, please contibute them back to the community!

Browser Compatibility

Haptics.js is supported by all browsers that implement the HTML5 navigator.vibrate API. As of 2014, Firefox, Chrome, and Opera have implemented this API.

Get started in 10 minutes.

Getting started with Haptics.js is easy! First, include the JavaScript file in your page using a <script> tag:

<script type="text/javascript" src="//raw.githubusercontent.com/shantanubala/haptics.js/master/haptics.js"></script>

We only recommend using GitHub for testing and prototyping. Once you're ready to deploy in production, download the haptics.js file and serve it from your own server or CDN directly -- it will load much faster.

Deliver a Vibration

Haptics.js provides a cross-browser vibrate function that accepts a single duration or array with durations and gaps. The following causes a device to vibrate for 200 milliseconds:

Haptics.vibrate(200);

Run Code

Haptics.js also allows you to create temporal patterns of vibration. The following code vibrates for 400ms, pauses for 200ms, vibrates for 1,000ms, pauses for 200ms, and vibrates for 400ms:

Haptics.vibrate([400, 200, 1000, 200, 400]);

Run Code

Feel a Beat

In addition to allowing you to send individual pulses of vibration, Haptics.js includes a number of built-in effects that can help you quickly create a more interactive application. A heartbeat is a great way to indicate loading or pace:

Haptics.heartbeat(500);

Run Code

The above code runs a "heartbeat" pattern lasting for 1 second. You can also provide an array of durations with the same API as Haptics.vibrate:

Haptics.heartbeat([500, 500, 500]);

Run Code

The code above will present the user with a heartbeat for 500ms, pause for 500ms, and then present a second heartbeat for 500ms.

Get a Fade

In addition to heartbeats, you can fade in with vibration:

Haptics.fadeIn(1000);

Run Code

You can also provide a sequences of vibrations that fade in:

Haptics.fadeIn([500, 100, 500]);

Run Code

You can also fade out:

Haptics.fadeOut(1000);

Likewise, you can provide a sequence of vibrations that fade out:

Haptics.fadeOut([500, 100, 500]);

Run Code

Pulse Width Modulation (PWM)

Vibration motors in most cell phones don't allow you to control the intensity of vibration. Instead, they have binary states -- "on" and "off". To simulate the feeling of a less intense vibration, you can use pulse width modulation to rapidly turn the vibration motor on and off. Since the vibration motor is only on for a fraction of the time, it feels like a less intense vibration.

PWM in Haptics.js

Haptics.js provides a simple PWM implementation:

var on = 30, off = 10, duration = 500;
Haptics.pwm(duration, on, off);

Run Code

The above code will create a vibration lasting 500ms consisting of small vibrotactile pulses lasting 30ms in duration with a 10ms gap between each pulse to reduce the overall intensity.

Creating PWM Functions

You can create a shortcut for your own PWM settings using the Haptics.createPatternPWM function. The code below delivers the same PWM pulse as the code above, but it creates a reusable function with the desired settings:

var mediumPWM = Haptics.createPatternPWM(30, 10);
mediumPWM(500);

Run Code

Any functions created using Haptics.createPatternPWM follow the same conventions as Haptics.vibrate, and also accept arrays as parameters:

var mediumPWM = Haptics.createPatternPWM(30, 10);
mediumPWM([500, 100, 500]);

Run Code

Create Custom Vibration Patterns

In addition to using the patterns provided, Haptics.js provides a set of utilities that allow you to quickly create your own vibration patterns. You can use a function, an array, or a set of functions.

Create a Pattern Function

Every pattern function must accept a single integer value for duration. Here is an example:

function newPattern(duration) {
    var chunk = duration / 3;
    Haptics.vibrate([chunk, chunk, chunk]);
}

Run Code

The above pattern newPattern will take a duration and turn on the vibration motor for a third of the duration, pause for a third of the duration, and turn the motor on again for a third of the duration. To allow your pattern to accept arrays of integers, Haptics.js provides a Haptics.createPattern utility:

Haptics.thirdPattern = Haptics.createPattern(newPattern);

From here, the function Haptics.thirdPattern can be used just like Haptics.vibrate -- it will accept either an integer or an array of integer durations:

Haptics.thirdPattern([500, 100, 500]);
Haptics.thirdPattern(500);

Run Code

Create a Duration Array

The Haptics.sequenceFactor function doesn't just accept a function as a parameter -- it also accepts arrays. Instead of creating a function that takes the duration as input, you can specify integer values that act as ratios. This feature is easiest to illustrate with a quick example:

Haptics.thirdPattern = Haptics.createPattern([1, 1, 1]);

Run Code

The above code creates an equivalent Haptics.thirdPattern function with fewer lines of code. The ratios can be modified a little bit:

Haptics.fifthPattern = Haptics.createPattern([2, 1, 2]);
Haptics.fifthPattern(500);

Run Code

The above code will result in a 200ms vibration, followed by a 100ms pause, followed by a 200ms vibration. Note that integer division is used to generate the final vibration pattern, so durations may be off by up to 1ms for each pulse.

Combine Existing Patterns

Two or more vibration patterns can be quickly combined into a single pattern using the Haptics.patternFactory function. Simply provide each pattern as a parameter. For example, to create a vibration that fades in and then fades out, you can combine the Haptics.fadeIn and Haptics.fadeOut functions as shown below:

Haptics.fadeInOut = Haptics.patternFactory(Haptics.fadeIn, Haptics.fadeOut);

Run Code

As you can see, Haptics.js is not just a way to turn on the vibration motor. Instead, it's a fun framework for building more interesting temporal patterns and vibrotactile sensations. Enjoy!