Capacitor plugin to detect shake gestures.
- 📳 Shake detection: Detect physical shake gestures on the device.
- 🎚️ Sensitivity: Configure how strong a shake must be to trigger an event.
- 🔋 Battery-friendly: The sensor is only active while you are watching for shakes.
- 📱 Cross-platform: One consistent API for Android and iOS.
- 🤝 Compatibility: Works alongside the Accelerometer, Gyroscope and Haptics plugins.
- 🔁 Up-to-date: Always supports the latest Capacitor version.
Missing a feature? Just open an issue and we'll take a look!
The Shake plugin is typically used to trigger an action when the user shakes the device, for example:
- Feedback and bug reporting: Let users shake the device to open a feedback or bug report dialog.
- Debug menus: Open a hidden developer or debug menu in internal builds when the device is shaken.
- Undo actions: Offer a shake-to-undo interaction, a gesture many users already know from iOS.
- Refresh content: Reload data or shuffle content when a shake gesture is detected.
| Plugin Version | Capacitor Version | Status |
|---|---|---|
| 0.x.x | >=8.x.x | Active support |
- The Complete Guide to Capacitor Device Sensors: How shake gestures relate to the Accelerometer and Gyroscope for shake-to-undo and shake-to-reroll interactions.
You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:
npx skills add capawesome-team/skills --skill capacitor-pluginsThen use the following prompt:
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-shake` plugin in my project.
If you prefer Manual Setup, install the plugin by running the following command:
npm install @capawesome/capacitor-shake
npx cap syncThis plugin is available on Android and iOS. On Web, all methods reject as unimplemented.
No additional permissions or privacy descriptions are required.
No configuration required for this plugin.
The following examples show how to detect shake gestures and stop detecting them.
Attach a shake listener and start watching for shake gestures. Use the sensitivity option to control how strong a shake must be to trigger an event (see Sensitivity Levels). Only available on Android and iOS:
import { Shake } from '@capawesome/capacitor-shake';
const startWatching = async () => {
await Shake.addListener('shake', () => {
console.log('Shake detected!');
});
await Shake.startWatching({ sensitivity: 'medium' });
};Stop watching and remove all listeners when you no longer need shake detection, for example when the user leaves the corresponding screen. The sensor is only active while you are watching, so this keeps the plugin battery-friendly:
import { Shake } from '@capawesome/capacitor-shake';
const stopWatching = async () => {
await Shake.stopWatching();
await Shake.removeAllListeners();
};startWatching(...)stopWatching()addListener('shake', ...)removeAllListeners()- Interfaces
- Type Aliases
startWatching(options?: StartWatchingOptions | undefined) => Promise<void>Start watching for shake gestures.
Only available on Android and iOS.
| Param | Type |
|---|---|
options |
StartWatchingOptions |
Since: 0.1.0
stopWatching() => Promise<void>Stop watching for shake gestures.
Only available on Android and iOS.
Since: 0.1.0
addListener(eventName: 'shake', listenerFunc: () => void) => Promise<PluginListenerHandle>Called when a shake gesture is detected.
Only available on Android and iOS.
| Param | Type |
|---|---|
eventName |
'shake' |
listenerFunc |
() => void |
Returns: Promise<PluginListenerHandle>
Since: 0.1.0
removeAllListeners() => Promise<void>Remove all listeners for this plugin.
Since: 0.1.0
| Prop | Type | Description | Default | Since |
|---|---|---|---|---|
sensitivity |
Sensitivity |
The sensitivity of the shake detection. Use 'light' to detect gentle shakes and 'hard' to only detect strong shakes. Only available on Android and iOS. |
'medium' |
0.1.0 |
| Prop | Type |
|---|---|
remove |
() => Promise<void> |
'hard' | 'light' | 'medium'
The sensitivity option controls how strong a shake must be to emit a shake event:
light: A gentle shake is enough to trigger an event.medium: A moderate shake is required to trigger an event (default).hard: Only a strong shake triggers an event.
It focuses on doing one thing well: detecting physical shake gestures on Android and iOS through a single, fully typed API. You can tune how strong a shake must be with three sensitivity levels, and the motion sensor only runs between startWatching(...) and stopWatching(), so it stays battery-friendly. It is actively maintained against the latest Capacitor version, giving you consistent shake behavior on both platforms from one dependency.
The plugin is available on Android and iOS. On the Web, all methods reject as unimplemented, since browsers do not provide a comparable shake detection API.
No, the plugin is designed to be battery-friendly. The motion sensor is only active between startWatching(...) and stopWatching(), so no sensor data is processed while you are not watching for shakes. Remember to call stopWatching() and removeAllListeners() when you no longer need shake detection.
Pass the sensitivity option to startWatching(...). Use light to detect gentle shakes, medium (the default) for moderate shakes, or hard to only detect strong shakes. See Sensitivity Levels for details.
No, the plugin does not require any additional permissions or privacy descriptions on Android or iOS. You can install it and start watching for shake gestures right away.
Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
- Accelerometer: Capture the acceleration force along the x, y, and z axes.
- Gyroscope: Read the device's gyroscope sensor.
- Haptics: Provide haptic feedback such as impacts, notifications, and vibrations.
Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.
See CHANGELOG.md.
See LICENSE.