preference
Sets various options as pairs of name/value attributes. Each preference's name is case-insensitive. Many preferences are unique to specific platforms, and will be indicated as such.
| Attributes(type) Only for platform: | Description |
|---|---|
| AllowInlineMediaPlayback(boolean) iOS |
Default: false Set to true to allow HTML5 media playback to appear inline within the screen layout, using browser-supplied controls rather than native controls. For this to work, add the webkit-playsinline attribute to any <video> elements. |
| AndroidLaunchMode(string) Android |
Default: singleTop Allowed values: standard, singleTop, singleTask, singleInstance Sets the Activity android:launchMode attribute. This changes what happens when the app is launched from app icon or intent and is already running. |
| android-maxSdkVersion(integer) Android |
Default: Not Specified Sets the maxSdkVersion attribute of the <uses-sdk> tag in the project's AndroidManifest.xml (see here). |
| android-minSdkVersion(integer) Android |
Default: Dependent on cordova-android Version Sets the minSdkVersion attribute of the <uses-sdk> tag in the project's AndroidManifest.xml (see here). |
| android-targetSdkVersion(integer) Android |
Default: Dependent on cordova-android Version Sets the targetSdkVersion attribute of the <uses-sdk> tag in the project's AndroidManifest.xml (see here). |
| AppendUserAgent(string) AndroidiOS | If set, the value will append to the end of old UserAgent of webview. When using with OverrideUserAgent, this value will be ignored. |
| BackgroundColor(string) AndroidBlackBerryWindows | Sets the app's background color. Supports a four-byte hex value, with the first byte representing the alpha channel, and standard RGB values for the following three bytes. For Windows, the alpha channel is ignored. Note: transparent value will set the application tile background to the accent color on Windows. |
| BackupWebStorage(string) iOS |
Default: cloud Allowed values: none, local, cloud. Set to cloud to allow web storage data to backup via iCloud. Set to local to allow only local backups via iTunes sync. Set to none prevent web storage backups. |
| ChildBrowser(string) BlackBerry |
Default: enable Disables child browser windows. By default, apps launch a secondary browser window to display resources accessed via window.open() or by specifying a _blank anchor target. Specify disable to override this default behavior. |
| CordovaWebViewEngine(string) iOS |
Default: CDVUIWebViewEngine This sets the WebView engine plugin to be used to render the host app. The plugin must conform to the CDVWebViewEngineProtocol protocol. The 'value' here should match the 'feature' name of the WebView engine plugin that is installed. This preference usually would be set by the WebView engine plugin that is installed, automatically. |
| DefaultVolumeStream(string) Android |
Default: default Added in cordova-android 3.7.0, This preference sets which volume the hardware volume buttons link to. By default this is "call" for phones and "media" for tablets. Set this to "media" to have your app's volume buttons always change the media volume. Note that when using Cordova's media plugin, the volume buttons will dynamically change to controlling the media volume when any Media objects are active. |
| DisallowOverscroll(boolean) iOSAndroid |
Default: false Set to true if you don't want the interface to display any feedback when users scroll past the beginning or end of content. On iOS, overscroll gestures cause content to bounce back to its original position. on Android, they produce a more subtle glowing effect along the top or bottom edge of the content. |
| EnableViewportScale(boolean) iOS |
Default: false Set to true to allow a viewport meta tag to either disable or restrict the range of user scaling, which is enabled by default. Place a viewport such as the following in the HTML to disable scaling and fit content flexibly within the rendering WebView: <meta name='viewport' content='width=device-width, initial-scale=1, user-scalable=no' />
|
| EnableWebGL(boolean) OS X |
Default: false (OS X 4.0.0+) Set to true to enable WebGL on the web view. |
| ErrorUrl(URL) Android |
Default: null If set, will display the referenced page upon an error in the application instead of a dialog with the title "Application Error". |
| ErrorUrl(string) iOS | If set, will display the referenced local page upon an error in the application. |
| ForegroundText(string) Windows |
Default: "light" Works for Windows 8.1 projects only. Allowed values: "light", "dark". Set to "dark" if you use the BackgroundColor="white" or another light color to avoid Windows Store submissions errors. |
| FullScreen(boolean) Android |
Default: false Allows you to hide the status bar at the top of the screen. Note: Recommended platform-agnostic way to achieve this is to use the StatusBar plugin. |
| GapBetweenPages(float) iOS |
Default: 0 The size of the gap, in points, between pages. |
| HideKeyboardFormAccessoryBar(boolean) BlackBerry |
Default: false Set to true to hide the additional toolbar that appears above the keyboard, helping users navigate from one form input to another. |
| HideMousePointer(integer) OS X |
Default: -1 (OS X 4.0.0+) Sets the timeout for hiding the mouse pointer. Set to 0 for immediate, set to -1 for never. |
| InAppBrowserStorageEnabled (boolean) Android |
Default: true Controls whether pages opened within an InAppBrowser can access the same localStorage and WebSQL storage as pages opened with the default browser. |
| KeepRunning(boolean) Android |
Default: true Determines whether the application stays running in the background even after a pause event fires. Setting this to false does not kill the app after a pause event, but simply halts execution of code within the cordova webview while the app is in the background. |
| KeyboardDisplayRequiresUserAction(boolean) iOS |
Default: true Set to false to allow the keyboard to appear when calling focus() on form inputs. |
| LoadUrlTimeoutValue(number in milliseconds) Android |
Default: 20000, 20 seconds When loading a page, the amount of time to wait before throwing a timeout error. |
| LoadingDialog(string) Android |
Default: null If set, displays a dialog with the specified title and message, and a spinner, when loading the first page of an application. The title and message are separated by a comma in this value string, and that comma is removed before the dialog is displayed. |
| LogLevel(string) Android |
Default: ERROR Allowed values: ERROR, WARN, INFO, DEBUG, VERBOSE Sets the minimum log level through which log messages from your application will be filtered. |
| MediaPlaybackAllowsAirPlay(boolean) iOS |
Default: true Set to false to prevent Air Play from being used in this view. Available in default UIWebView and WKWebView. |
| MediaPlaybackRequiresUserAction(boolean) iOS |
Default: false Set to true to prevent HTML5 videos or audios from playing automatically with the autoplay attribute or via JavaScript. |
| Min/Max Version(Regex) Windows | Allowed values: /(Microsoft.+? | Windows.+?)-(MinVersion | MaxVersionTested)/i Identifies the ecosystems and their min/max versions the app is compatible with. There are three parts to each value: the SDK, the version restriction, and the version value. These preferences are detected by beginning with Windows or Microsoft and ending in -MinVersion or -MaxVersionTested:
Note: These preferences are only set in the appxmanifest files of the desired target-platform and not in the jsproj files. |
| Orientation(string) |
Default: default Allowed values: default, landscape, portrait Allows you to lock orientation and prevent the interface from rotating in response to changes in orientation. NOTE: The default value means Cordova will strip the orientation preference entry from the platform's manifest/configuration file allowing the platform to fallback to its default behavior. For iOS, to specify both portrait & landscape mode you would use the platform specific value 'all'. |
| OSXLocalStoragePath(string) OS X |
Default: ~/Library/Application Support/{bundle.id} (OS X 4.0.0+) Sets the directory for the local storage path. |
| OverrideUserAgent(string) Android | If set, the value will replace the old UserAgent of webview. It is helpful to identify the request from app/browser when requesting remote pages. Use with caution, this may causes compitiable issue with web servers. For most cases, use AppendUserAgent instead. |
| PageLength(float) iOS |
Default: 0 The size of each page, in points, in the direction that the pages flow. When PaginationMode is right to left or left to right, this property represents the width of each page. When PaginationMode is topToBottom or bottomToTop, this property represents the height of each page. The default value is 0, which means the layout uses the size of the viewport to determine the dimensions of the page. |
| PaginationBreakingMode(string) iOS |
Default: page Allowed values: page, column Valid values are page and column.The manner in which column- or page-breaking occurs. This property determines whether certain CSS properties regarding column- and page-breaking are honored or ignored. When this property is set to column, the content respects the CSS properties related to column-breaking in place of page-breaking. |
| PaginationMode(string) iOS |
Default: unpaginated Allowed values: unpaginated, leftToRight, topToBottom, bottomToTop, rightToLeft This property determines whether content in the web view is broken up into pages that fill the view one screen at a time,or shown as one long scrolling view. If set to a paginated form, this property toggles a paginated layout on the content, causing the web view to use the values of PageLength and GapBetweenPages to relayout its content. |
| PopupBlocker(string) BlackBerry |
Default: enable Enables the popup blocker, which prevents calls to window.open(). By default, popups display in a child browser window. Setting the preference to enable prevents it from displaying at all. |
| SetFullscreen(boolean) Android |
Default: false Same as the Fullscreen parameter in the global configuration of this xml file. This Android-specific element is deprecated in favor of the global Fullscreen element, and will be removed in a future version. |
| ShowTitle(boolean) Android |
Default: false Show the title at the top of the screen. |
| SplashScreenBackgroundColor Windows |
Default: #464646 Sets the splashscreen background color. Supports a CSS color name or a four-byte hex value, with the first byte representing the alpha channel, and standard RGB values for the following three bytes. The alpha channel is ignored although transparent value will cause black/white background color in case of Dark/Light theme accordingly. |
| Suppresses3DTouchGesture(boolean) iOS |
Default: false Set to true to avoid 3D Touch capable iOS devices rendering a magnifying glass widget when the user applies force while longpressing the webview. Test your app thoroughly since this disables onclick handlers, but plays nice with ontouchend. If this setting is true, SuppressesLongPressGesture will effectively be true as well. |
| SuppressesIncrementalRendering(boolean) iOS |
Default: false Set to true to wait until all content has been received before it renders to the screen. |
| SuppressesLongPressGesture(boolean) iOS |
Default: false Set to true to avoid iOS9+ rendering a magnifying glass widget when the user longpresses the webview. Test your app thoroughly since this may interfere with text selection capabilities. |
| TopActivityIndicator(string) iOS |
Default: gray Allowed values: whiteLarge, white, gray. Controls the appearance of the small spinning icon in the status bar that indicates significant processor activity. |
| uap-target-min-version(string) Windows | This property sets the MinTargetVersion for the Windows UAP. If not specified, this is set to the initial release version 10.0.10240.0 Note: This preference is set in the jsproj file and not in the appxmanifest file. So users with OS version lower than this value would not be able to run the app. |
| UIWebViewDecelerationSpeed(string) iOS |
Default: normal Allowed values: normal, fast This property controls the deceleration speed of momentum scrolling. normal is the default speed for most native apps, and fast is the default for Mobile Safari. |
| WebSecurity(string) BlackBerry |
Default: enable Set to disable to override web security settings, allowing access to remote content from unknown sources. This preference is intended as a development convenience only, so remove it before packaging the app for distribution. For the released app, all URIs should be known and whitelisted using the element, described in the Domain Whitelist Guide. |
| WindowSize(string) OS X |
Default: auto (OS X 4.0.0+) Sets the size of the application window. Accepts the format WxH for a specific width and height or the special values auto and fullscreen. The latter will open a borderless window spanning the entire desktop area. Please note, that this is different from the normal OS X fullscreen mode, which would never span multiple displays. Note: The global cordova fullscreen preference has no effect in OS X. |
| WindowsDefaultUriPrefix(string) Windows | Allowed values: ms-appx://, ms-appx-web:// Identifies whether you want your app to target the local context or remote context as its startup URI. When building for Windows 10, the default is the remote context ( ms-appx-web://). In order to have a local-mode application that is not impacted by Remote Mode capability restrictions, you must set this preference to ms-appx:// and not declare any <access> elements with remote URIs. The local mode is the default for Windows 8.1 |
| WindowsStoreDisplayName(string) Windows | A friendly name for the publisher that can be displayed to users. |
| WindowsStoreIdentityName(string) Windows | Identity name used for Windows store. The identity defines a globally unique identifier for a package. A package identity is represented as a tuple of attributes of the package. See the identity page on the package manifest schema reference for further details. |
| WindowsStorePublisherName(string) Windows | Publisher Display Name. |
| WindowsToastCapable(boolean) Windows |
Default: false A value of true indicates that the app is allowed to provide 'toast notifications'. |
| deployment-target(string) iOS | This sets the IPHONEOSDEPLOYMENTTARGET in the build, which ultimately tranlsates to the MinimumOSVersion in the ipa. For more details please refer to Apple's documentation on Deployment Target Settings |
| target-device(string) iOS |
Default: universal Allowed values: handset, tablet, universal This property maps directly to TARGETEDDEVICEFAMILY in the xcode project. Note that if you target universal (which is the default) you will need to supply screen shots for both iPhone and iPad or your app may be rejected. |
| windows-phone-target-version(string) Windows | Sets the version of Windows Phone for which the package (resulting from cordova build) will target. If none is specified, it will be set to the same version as windows-target-version (if found). |
| windows-target-version(string) Windows | Sets the version of Windows for which the package (resulting from cordova build) will target. If none is specified, it will be set to '8.1'. |
Examples:
<preference name="DisallowOverscroll" value="true"/> <preference name="Fullscreen" value="true" /> <preference name="BackgroundColor" value="0xff0000ff"/> <preference name="HideKeyboardFormAccessoryBar" value="true"/> <preference name="Orientation" value="landscape" /> <!-- iOS only preferences --> <preference name="EnableViewportScale" value="true"/> <preference name="MediaPlaybackAllowsAirPlay" value="false"/> <preference name="MediaPlaybackRequiresUserAction" value="true"/> <preference name="AllowInlineMediaPlayback" value="true"/> <preference name="BackupWebStorage" value="local"/> <preference name="TopActivityIndicator" value="white"/> <preference name="SuppressesIncrementalRendering" value="true"/> <preference name="GapBetweenPages" value="0"/> <preference name="PageLength" value="0"/> <preference name="PaginationBreakingMode" value="page"/> <preference name="PaginationMode" value="unpaginated"/> <preference name="UIWebViewDecelerationSpeed" value="fast" /> <preference name="ErrorUrl" value="myErrorPage.html"/> <preference name="OverrideUserAgent" value="Mozilla/5.0 My Browser" /> <preference name="AppendUserAgent" value="My Browser" /> <preference name="target-device" value="universal" /> <preference name="deployment-target" value="7.0" /> <preference name="CordovaWebViewEngine" value="CDVUIWebViewEngine" /> <preference name="SuppressesLongPressGesture" value="true" /> <preference name="Suppresses3DTouchGesture" value="true" /> <!-- Android only preferences --> <preference name="KeepRunning" value="false"/> <preference name="LoadUrlTimeoutValue" value="10000"/> <preference name="InAppBrowserStorageEnabled" value="true"/> <preference name="LoadingDialog" value="My Title,My Message"/> <preference name="ErrorUrl" value="myErrorPage.html"/> <preference name="ShowTitle" value="true"/> <preference name="LogLevel" value="VERBOSE"/> <preference name="AndroidLaunchMode" value="singleTop"/> <preference name="DefaultVolumeStream" value="call" /> <preference name="OverrideUserAgent" value="Mozilla/5.0 My Browser" /> <preference name="AppendUserAgent" value="My Browser" /> <!-- Windows only preferences --> <preference name="windows-phone-target-version" value="8.1" /> <preference name="windows-target-version" value="8.1" /> <preference name="Windows.Universal" value="10.0.10240.0" /> <preference name="WindowsDefaultUriPrefix" value="ms-appx://" /> <preference name="Windows.Mobile-MaxVersionTested" value="10.0.10031.0" /> <preference name="Windows.Universal-MinVersion" value="10.0.0.0" /> <preference name="WindowsStoreIdentityName" value="Cordova.Example.ApplicationDataSample" /> <preference name="WindowsStorePublisherName" value="CN=Contoso Corp, O=Contoso Corp, L=Redmond, S=Washington, C=US" /> <preference name="WindowsToastCapable" value="true" /> <preference name="uap-target-min-version" value="10.0.10586.0" /> <!-- BlackBerry only preferences --> <preference name="ChildBrowser" value="disable"/> <preference name="PopupBlocker" value="enable"/> <preference name="WebSecurity" value="disable"/> <!-- OS X only preferences --> <preference name="HideMousePointer" value="5"/> <preference name="OSXLocalStoragePath" value="~/.myapp/database"/> <preference name="WindowSize" value="800x400"/> <preference name="EnableWebGL" value="true"/>
Please login to continue.