This specification defines an API that provides access to the
vibration mechanism of the hosting device. Vibration is a form of
Status of This Document
This section describes the status of this document at the
time of its publication. Other documents may supersede this
document. A list of current W3C publications and the latest
revision of this technical report can be found in the W3C technical reports index
No changes were brought to the document since its publication
as a Proposed Recommendation . By publishing this Recommendation,
W3C expects that the functionality
specified in this document will not be affected by changes to Web
IDL as it proceeds to Recommendation.
This document represents the consensus
of the group
the scope and features of
the Vibration API. It should be noted
the group is aware of more advanced use cases
that cannot be realized using this simpler first version. The
This document has been reviewed by W3C
Members, by software developers, and by other W3C groups and
interested parties, and is endorsed by the Director
as a W3C Recommendation. It is a stable document
and may be used as reference material
or cited from another document. W3C 's role in making the
Recommendation is to draw
attention to the specification and to promote its widespread
deployment. This enhances the functionality and interoperability of
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. This
API is not meant to be used as a generic notification mechanism.
Such use cases may be handled using the Notifications
API [ NOTIFICATIONS ] specification. In
addition, determining whether vibration is enabled is out of scope
for this specification.
As well as sections marked as non-normative, all authoring
guidelines, diagrams, examples, and notes in this specification are
non-normative. Everything else in this specification is
The key words MAY and , MUST ,
are to be interpreted as described in
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.
If the hiddenattribute [ PAGE-VISIBILITY ] is set to true, , then return
false and terminate these steps.
A trusted (also known as privileged) application that
integrates closely with the operating system's functionality may
vibrate the device even if such an application is not visible at
all, and thus may ignore the previous step.
To validate and normalize a
vibration pattern given pattern , run these steps:
If pattern is a list, proceed to the next step.
Otherwise run the following substeps:
Let list be an initially empty list, and add
pattern to list .
Set pattern to list .
Let max length be an implementation-dependent
maximum length of pattern .
If the length of a pattern is greater than max length
an implementation of this API could consider breaking the request
effectively into multiple shorter requests internally to achieve
the same effect, rather than ignoring what follows the max length.
There are cases, however, where it is appropriate to ignore the
pattern exceeding the max length. An example is if the length is so
long that it would effectively create a denial of service attack on
the user. A web application might also make multiple requests if it
is known to the application that the length is too long for some
implementations and a possible gap in between patterns is
If the length of pattern is greater than max
length , truncate pattern , leaving only the first
max length entries.
If the length of the
pattern is even and not zero then the last entry in the
pattern will have no effect so an implementation can remove it from
the pattern at this point.
Let max duration be an implementation-dependent
maximum duration for a single vibration entry in a
For each entry in pattern whose value is greater
than max duration , set the entry's value to max
Return pattern .
vibration using pattern , run these steps:
An implementation MAY
return false and terminate these steps.
For example, an implementation might abort the
algorithm because the user has set a preference indicating that pages
at a given origin should never be able to vibrate the device, or an
implementation might cap the total amount of time a page may cause
the device to vibrate and reject requests in excess of this
If another instance of the perform vibration
algorithm is already running, run the following substeps:
In the following example the device will vibrate for 1000
// vibrate for 1000 msnavigator
// or alternatively
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
navigator.vibrate([50, 100, 150]);
The following example cancels any existing vibrations:
// cancel any existing vibrationsnavigator
// or alternatively
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.
Thanks to Anne van Kesteren for suggestions on how to make the
specification reusable in other contexts.
B.1 Normative references
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead;
Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5 . 28 October 2014.
W3C Recommendation. URL: http://www.w3.org/TR/html5/