Skip to main content
Version: v8

Config

Ionic Config provides a way to change the properties of components globally across an app. It can set the app mode, tab button layout, animations, and more.

Global Config

The available config keys can be found in the IonicConfig interface.

The following example disables ripple effects and default the mode to Material Design:

example.js
window.Ionic = {
config: {
rippleEffect: false,
mode: 'md',
},
};

Per-Component Config

Ionic Config is not reactive. Updating the config's value after the component has rendered will result in the previous value. It is recommended to use a component's properties instead of updating the config, when you require reactive values.

Not recommended

window.Ionic = {
config: {
// Not recommended when your app requires reactive values
backButtonText: 'Go Back',
},
};

Recommended

<ion-back-button></ion-back-button>

<script>
const backButton = document.querySelector('ion-back-button');

/**
* The back button text can be updated
* anytime the locale changes.
*/
backButton.text = 'Go Back';
</script>

Per-Platform Config

Ionic Config can also be set on a per-platform basis. For example, this allows you to disable animations if the app is being run in a browser on a potentially slower device. Developers can take advantage of the Platform utilities to accomplish this.

In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser.

note

Since the config is set at runtime, you will not have access to the Platform Dependency Injection. Instead, you can use the underlying functions that the provider uses directly.

See the Angular Platform Documentation for the types of platforms you can detect.

app.module.ts
import { isPlatform, IonicModule } from '@ionic/angular';

@NgModule({
...
imports: [
IonicModule.forRoot({
animated: !isPlatform('mobileweb')
})
],
...
})

Fallbacks

The next example allows you to set an entirely different configuration based upon the platform, falling back to a default config if no platforms match:

app.module.ts
import { isPlatform, IonicModule } from '@ionic/angular';

const getConfig = () => {
let config = {
animated: false
};

if (isPlatform('iphone')) {
config = {
...config,
backButtonText: 'Previous'
}
}

return config;
}
@NgModule({
...
imports: [
IonicModule.forRoot(getConfig())
],
...
});

Overrides

This final example allows you to accumulate a config object based upon different platform requirements.

app.module.ts
import { isPlatform, IonicModule } from '@ionic/angular';

const getConfig = () => {
if (isPlatform('hybrid')) {
return {
tabButtonLayout: 'label-hide'
}
}

return {
tabButtonLayout: 'icon-top'
};
}
@NgModule({
...
imports: [
IonicModule.forRoot(getConfig())
],
...
});

Reading the Config (Angular)

Ionic Angular provides a Config provider for accessing the Ionic Config.

get

DescriptionReturns a config value as an any. Returns null if the config is not defined.
Signatureget(key: string, fallback?: any) => any

Examples

import { Config } from '@ionic/angular';

@Component(...)
class AppComponent {
constructor(config: Config) {
const mode = config.get('mode');
}
}

getBoolean

DescriptionReturns a config value as a boolean. Returns false if the config is not defined.
SignaturegetBoolean(key: string, fallback?: boolean) => boolean

Examples

import { Config } from '@ionic/angular';

@Component(...)
class AppComponent {
constructor(config: Config) {
const swipeBackEnabled = config.getBoolean('swipeBackEnabled');
}
}

getNumber

DescriptionReturns a config value as a number. Returns 0 if the config is not defined.
SignaturegetNumber(key: string, fallback?: number) => number

Interfaces

IonicConfig

Below are the config options that Ionic uses.

ConfigTypeDescription
actionSheetEnterAnimationBuilderProvides a custom enter animation for all ion-action-sheet, overriding the default "animation".
actionSheetLeaveAnimationBuilderProvides a custom leave animation for all ion-action-sheet, overriding the default "animation".
alertEnterAnimationBuilderProvides a custom enter animation for all ion-alert, overriding the default "animation".
alertLeaveAnimationBuilderProvides a custom leave animation for all ion-alert, overriding the default "animation".
animatedbooleanIf true, Ionic will enable all animations and transitions across the app.
backButtonDefaultHrefstringOverrides the default value for the defaultHref property in all <ion-back-button> components.
backButtonIconstringOverrides the default icon in all <ion-back-button> components.
backButtonTextstringOverrides the default text in all <ion-back-button> components.
innerHTMLTemplatesEnabledbooleanRelevant Components: ion-alert, ion-infinite-scroll-content, ion-loading, ion-refresher-content, ion-toast. If true, content passed to the relevant components will be parsed as HTML instead of plaintext. Defaults to false.
hardwareBackButtonbooleanIf true, Ionic will respond to the hardware back button in an Android device.
infiniteLoadingSpinnerSpinnerTypesOverrides the default spinner type in all <ion-infinite-scroll-content> components.
loadingEnterAnimationBuilderProvides a custom enter animation for all ion-loading, overriding the default "animation".
loadingLeaveAnimationBuilderProvides a custom leave animation for all ion-loading, overriding the default "animation".
loadingSpinnerSpinnerTypesOverrides the default spinner for all ion-loading overlays.
menuIconstringOverrides the default icon in all <ion-menu-button> components.
menuTypestringOverrides the default menu type for all <ion-menu> components.
modalEnterAnimationBuilderProvides a custom enter animation for all ion-modal, overriding the default "animation".
modalLeaveAnimationBuilderProvides a custom leave animation for all ion-modal, overriding the default "animation".
modeModeThe mode determines which platform styles to use for the whole application.
navAnimationAnimationBuilderOverrides the default "animation" of all ion-nav and ion-router-outlet across the whole application.
pickerEnterAnimationBuilderProvides a custom enter animation for all ion-picker, overriding the default "animation".
pickerLeaveAnimationBuilderProvides a custom leave animation for all ion-picker, overriding the default "animation".
platformPlatformConfigOverrides the default platform detection methods.
popoverEnterAnimationBuilderProvides a custom enter animation for all ion-popover, overriding the default "animation".
popoverLeaveAnimationBuilderProvides a custom leave animation for all ion-popover, overriding the default "animation".
refreshingIconstringOverrides the default icon in all <ion-refresh-content> components.
refreshingSpinnerSpinnerTypesOverrides the default spinner type in all <ion-refresh-content> components.
rippleEffectbooleanIf true, Material Design ripple effects will be enabled across the app.
sanitizerEnabledbooleanIf true, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML.
spinnerSpinnerTypesOverrides the default spinner in all <ion-spinner> components.
statusTapbooleanIf true, clicking or tapping the status bar will cause the content to scroll to the top.
swipeBackEnabledbooleanIf true, Ionic will enable the "swipe-to-go-back" gesture across the application.
tabButtonLayoutTabButtonLayoutOverrides the default "layout" of all ion-bar-button across the whole application.
toastDurationnumberOverrides the default duration for all ion-toast components.
toastEnterAnimationBuilderProvides a custom enter animation for all ion-toast, overriding the default "animation".
toastLeaveAnimationBuilderProvides a custom leave animation for all ion-toast, overriding the default "animation".
toggleOnOffLabelsbooleanOverrides the default enableOnOffLabels in all ion-toggle components.
experimentalCloseWatcherbooleanExperimental: If true, the CloseWatcher API will be used to handle all Escape key and hardware back button presses to dismiss menus and overlays and to navigate. Note that the hardwareBackButton config option must also be true.
focusManagerPriorityFocusManagerPriority[]Experimental: When defined, Ionic will move focus to the appropriate element after each page transition. This ensures that users relying on assistive technology are informed when a page transition happens. Disabled by default.