Need help with cordova-plugin-kiosk?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

134 Stars 81 Forks Apache License 2.0 53 Commits 22 Opened issues


Cordova plugin to use Cordova application "in kiosk mode" and as Android launcher

Services available


Need anything else?

Contributors list

No Data

Cordova Kiosk Mode

A Cordova plugin to create a Cordova application with "kiosk mode". An app with this plugin can be set as an Android launcher. If the app starts as a launcher, it blocks hardware buttons and statusbar, so an user cannot close the app until the app request it.

This plugin does not change behavior of application until it is set as launcher - home screen of the device.

Escape from the app is possible only using javascript call

or by uninstalling the app using
. (Keeping USB debug allowed necessary.) If the application starts as usual (not as a launcher), no restrictions are applied.
  • Official plugin website:
  • Example app:

This plugin is for Android platform only. For kiosk on iOS platform check its Guided Access feature.


By adding this Cordova plugin the Cordova app becomes a homescreen (also known as a launcher) of Android device and should block any attempt of user to leave it.

To add plugin into existing Cordova / Phonegap application use:

cordova plugin add

To add specific version of this plugin (like

) use:
cordova plugin add

Android platform files (like

) should be updated immediately. If you will modify plugin code, you will need to re-add android platform to plugin modifications take effect:
cordova platform rm android
cordova platform add android

To has it working, user have to set this application as launcher (see below) and start it by pressing Home button or by restarting the device.

WARNING Before installation ensure you have USB debug mode enabled. Without USB debug enabled you can get stuck in broken kiosk application.

Short API description

Exiting from Kiosk mode using Javascript in the page (for hidden/authenticated button to escape the kiosk application):


Detecting whether the app is successfly running in kiosk mode (kiosk activity is opened):

KioskPlugin.isInKiosk(function(isInKiosk){ ... });

Detecting whether the app (kiosk activity) is set as launcher:

KioskPlugin.isSetAsLauncher(function(isLauncher){ ... });

The device is effectively locked only when both methods returns

. When the app is "in kiosk", but not set as a launcher, user can escape the app by pressing a Home button (but other buttons are still locked).

Defining allowed buttons - buttons whose event propagation should not be prevented - so you can for example allow setting volume up/down:

KioskPlugin.setAllowedKeys([ 24, 25 ]); // KEYCODE_VOLUME_UP, KEYCODE_VOLUME_DOWN

For list of keycode values check KeyEvent reference:

For complete example application check:


  • To remove this application use

    : (Do not install it without USB debug mode enabled!) (com.example.hello replace with package of your app defined in your config.xml)

    $ANDROID_HOME/platform-tools/adb uninstall com.example.hello
  • To change launcher (reset setting which launcher is default):

    • Alcatel: Settings - Applications - All - (This Application) / Launcher - Clear defaults, after Home press will be asked for default to set
    • Xiaomi: Settings - Installed apps - Defaults - Launcher
  • To disable screenlock: ("slide to unlock")

    • Alcatel: Settings - Security - Set up screen lock - None
    • Xiaomi: Settings - Additional settings - Developer options - Skip screen lock

"Application Error - The connection to the server was unsuccessful. (file:///android_asset/www/index.html)" occurred

  • One reason can be too long loading of

    - you can set timeout of Cordova's WebView in
    of application: (value is in milliseconds)

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.