The config.xml File
Many aspects of an app's behavior can be controlled with a global
configuration file, config.xml
, that is placed in the top-level web
asset directory along with the app's home page. This
platform-agnostic XML file is formatted based on the W3C's Packaged
Web Apps (Widgets) specification, and
extended to specify core Cordova API features, plugins, and
platform-specific settings.
For projects created with the Cordova CLI (described in The
Command-line Interface), this file can be found in the top-level www
directory. Using the CLI to build a project regenerates versions of
this file in various subdirectories within platforms
. If you use the
CLI to create a project, but then shift your workflow to an SDK, the
platform-specific file serves as a source.
This section details global and cross-platform configuration options. See the following sections for platform-specific options:
Core Configuration Elements
This example shows the default config.xml
generated by the CLI's
create
command, described in The Command-line Interface:
<widget id="com.example.hello" version="0.0.1">
<name>HelloWorld</name>
<description>
A sample Apache Cordova application that responds to the deviceready event.
</description>
<author email="dev@callback.apache.org" href="http://cordova.io">
Apache Cordova Team
</author>
<content src="index.html" />
<access origin="*" />
<preference name="Fullscreen" value="true" />
<preference name="WebViewBounce" value="true" />
</widget>
The following configuration elements appear in the top-level
config.xml
file, and are supported across all supported Cordova
platforms:
-
The
<widget>
element'sid
attribute provides the app's reverse-domain identifier, and theversion
its full version number expressed in major/minor/patch notation. -
The
<name>
element specifies the app's formal name, as it appears on the device's home screen and within app-store interfaces. -
The
<description>
and<author>
elements specify metadata and contact information that may appear within app-store listings. -
The optional
<content>
element defines your application's starting page in the top-level web assets directory. The default value isindex.html
, which customarily appears in a project's top-levelwww
directory. -
<access>
elements define the set of external domains the app is allowed to communicate with. The default value shown above allows it to access any server. See the Domain Whitelist Guide for details. -
The
<preference>
tag sets various options as pairs ofname
/value
attributes. Each preference'sname
is case-insensitive. Many preferences are unique to specific platforms, as listed at the top of this page. The following sections detail preferences that apply to more than one platform.
Global Preferences
The following global preferences apply to all platforms:
-
Fullscreen
allows you to hide the status bar at the top of the screen. The default value isfalse
. Example:<preference name="Fullscreen" value="true" />
-
Orientation
allows you to lock orientation and prevent the interface from rotating in response to changes in orientation. Possible values aredefault
,landscape
, orportrait
. Example:<preference name="Orientation" value="landscape" />
NOTE: The
default
value means both landscape and portrait orientations are enabled. If you want to use each platform's default settings (usually portrait-only), leave this tag out of theconfig.xml
file. Also, BlackBerry usesauto
instead ofdefault
in itsconfig.xml
file. If you specifydefault
in the globalconfig.xml
, it translates toauto
in the BlackBerry build.
Multi-platform Preferences
The following preferences apply to more than one platform, but not to all of them:
-
DisallowOverscroll
(boolean, defaults tofalse
): set totrue
if you don't want the interface to display any feedback when users scroll past the beginning or end of content.<preference name="DisallowOverscroll" value="true"/>
Applies to Android and iOS. 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.
-
BackgroundColor
: Set 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. This example specifies blue:<preference name="BackgroundColor" value="0xff0000ff"/>
Applies to Android and BlackBerry. Overrides CSS otherwise available across all platforms, for example:
body{background-color:blue}
. -
HideKeyboardFormAccessoryBar
(boolean, defaults tofalse
): set totrue
to hide the additional toolbar that appears above the keyboard, helping users navigate from one form input to another.<preference name="HideKeyboardFormAccessoryBar" value="true"/>
Applies to iOS and BlackBerry.
NOTE: For BlackBerry, valid values are
enable
ordisable
.
The <feature>
Element
If you use the CLI to build applications, you use the plugin
command
to enable device APIs. This does not modify the top-level config.xml
file, so the <feature>
element does not apply to your workflow. If
you are working directly in an SDK and using the platform-specific
config.xml
file as source, you use the <feature>
tag to enable
device-level APIs and external plugins. They typically appear in this
form:
<feature name="Plugin" value="PluginID" />
They often appear with custom values in platform-specific config.xml
files. For example, here is how to specify the Device API for Android
projects:
<feature name="Device">
<param name="android-package" value="org.apache.cordova.device.Device" />
</feature>
Here is how the element appears for iOS projects:
<feature name="Device">
<param name="ios-package" value="CDVDevice" />
</feature>
See the API Reference for details on how to specify each feature. See the Plugin Development Guide for more information on plugins.