A library for enabling haptic effects on web sites using HTML5. In addition to providing a cross-browser wrapper, haptics.js also allows you to quickly create new tactile effects using vibrations.
Released under an MIT License
© 2016 Shantanu Bala and Somatic Labs
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.
Haptics.js can be added to any web page to provide enhanced interactivity and a more interesting user interface. Haptics.js is great for:
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!
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.
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.
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);
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]);
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);
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]);
The code above will present the user with a heartbeat for 500ms, pause for 500ms, and then present a second heartbeat for 500ms.
In addition to heartbeats, you can fade in with vibration:
Haptics.fadeIn(1000);
You can also provide a sequences of vibrations that fade in:
Haptics.fadeIn([500, 100, 500]);
You can also fade out:
Haptics.fadeOut(1000);
Likewise, you can provide a sequence of vibrations that fade out:
Haptics.fadeOut([500, 100, 500]);
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.
Haptics.js provides a simple PWM implementation:
var on = 30, off = 10, duration = 500;
Haptics.pwm(duration, on, off);
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.
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);
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]);
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.
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]);
}
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);
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]);
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);
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.
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);
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!