AppVeyor Travis CI
Build status Build Status

cordova-plugin-vibration

This plugin provides a way to vibrate the device. Its API aligns with the W3C vibration specification at http://www.w3.org/TR/vibration/

The plugin defines a global object/method navigator.vibrate. Although in the global scope, it is not available until after the deviceready event.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.vibrate);
}

Installation

cordova plugin add cordova-plugin-vibration

Supported Platforms

  • iOS
  • Windows Phone
  • Android
    The Android webview (API level 19 and up) supports the W3C Vibration API natively, so no Android specific implementation in this plugin is necessary.

navigator.vibrate

This function has three different functionalities based on parameters passed to it:

Standard vibrate

Vibrates the device for a given amount of time.

navigator.vibrate(time)

or

navigator.vibrate([time])
  • time: Milliseconds to vibrate the device. (Number)

Example

// Vibrate for 3 seconds
navigator.vibrate(3000);

// Vibrate for 3 seconds
navigator.vibrate([3000]);

Quirks

iOS Quirks
  • time: Ignores the specified time and vibrates for a pre-set amount of time.

      navigator.vibrate(3000); // 3000 is ignored
    
Windows Phone Quirks
  • time: Max time is 5000ms (5s) and min time is 1ms

      navigator.vibrate(8000); // will be truncated to 5000
    
Android Quirks

Calls to navigator.vibrate will immediately return false if user hasn't tapped on the frame or any embedded frame yet.

See https://www.chromestatus.com/feature/5644273861001216

Vibrate with a pattern

Vibrates the device with a given pattern

navigator.vibrate(pattern);
  • pattern: Sequence of durations (in milliseconds) for which to turn on or off the vibrator. (Array of Numbers)

Example

// Vibrate for 1 second
// Wait for 1 second
// Vibrate for 3 seconds
// Wait for 1 second
// Vibrate for 5 seconds
navigator.vibrate([1000, 1000, 3000, 1000, 5000]);

Quirks

  • Not supported on iOS

Cancel vibration

Immediately cancels any currently running vibration.

navigator.vibrate(0)

or

navigator.vibrate([])

or

navigator.vibrate([0])

Passing in a parameter of 0, an empty array, or an array with one element of value 0 will cancel any vibrations.

Quirks

  • Not supported on iOS