This document represents the consensus of the group on the scope and features of the Vibration API. It should be noted that the group is aware of more advanced use cases that cannot be realized using this simpler first version. The intent is to address them in a future revision.
The API is specifically designed to address use cases that require simple tactile feedback only. Use cases requiring more fine-grained control are out of scope for this specification. In addition, the API is not meant to be used as a generic notification mechanism.
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.
The concepts browsing context and spin the event loop are defined in [[!HTML5]].
vibrate() method, when invoked, MUST run the algorithm
for processing vibration patterns.
The rules for processing vibration patterns are as given in the following algorithm:
hiddenattribute [[!PAGE-VISIBILITY]] is set to true, then return false and terminate these steps.
visibilitychange event [[!PAGE-VISIBILITY]] is dispatched at
Document in a browsing context, the
user agent MUST cancel the
pre-existing instance of the processing vibration patterns
algorithm, if any.
In the following example the device will vibrate for 1000 milliseconds (ms):
// vibrate for 1000 ms navigator.vibrate(1000); // or alternatively navigator.vibrate();
In the following example the pattern will cause the device to vibrate for 50 ms, be still for 100 ms, and then vibrate for 150 ms:
navigator.vibrate([50, 100, 150]);
The following example cancels any existing vibrations:
// cancel any existing vibrations navigator.vibrate(0); // or alternatively navigator.vibrate();
The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas Sicking, and the Mozilla WebAPI team for their contributions, and for providing the WebVibrator prototype as an initial input.