Version: v6

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:

JavaScript
Angular
React
Vue

example.js

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

app.module.ts

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

@NgModule({
...
 imports:[
IonicModule.forRoot({
 rippleEffect:false,
 mode:'md'
})
],
...
})

The setupIonicReact function must be called before rendering any Ionic components (including IonApp).

App.tsx

import{ setupIonicReact }from'@ionic/react';

setupIonicReact({
 rippleEffect:false,
 mode:'md',
});

main.ts

import{IonicVue}from'@ionic/vue';
import{ createApp }from'vue';

createApp(App).use(IonicVue,{
 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.

JavaScript
Angular
React
Vue

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>

Not recommended

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

@NgModule({
...
 imports:[
 IonicModule.forRoot({
// Not recommended when your app requires reactive values
 backButtonText:'Go Back'
})
],
...
});

Recommended

<ion-back-button[text]="backButtonText"></ion-back-button>

@Component(...)
classMyComponent{
/**
 * The back button text can be updated
 * anytime the locale changes.
 */
 backButtonText ='Go Back';
}

Not recommended

import{ setupIonicReact }from'@ionic/react';

setupIonicReact({
// Not recommended when your app requires reactive values
 backButtonText:'Go Back',
});

Recommended

import{ useState }from'react';
import{IonBackButton}from'@ionic/react';

constExampleComponent=()=>{
const[backButtonText, setBackButtonText]=useState('Go Back');
return(
{/*
 * The back button text can be updated
 * anytime the locale changes.
 */}
<IonBackButtontext={backButtonText}></IonBackButton>
)
}

Not recommended

import{ IonicVue }from'@ionic/vue';
import{ createApp }from'vue';

// Not recommended when your app requires reactive values
createApp(App).use(IonicVue,{
 backButtonText:'Go Back',
});

Recommended

<template>
<ion-back-button[text]="backButtonText"></ion-back-button>
</template>

<scriptsetuplang="ts">
import{IonBackButton}from'@ionic/vue';
import{ ref }from'vue';

/**
 * The back button text can be updated
 * anytime the locale changes.
 */
const backButtonText =ref('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.

Angular
React
Vue

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')
})
],
...
})

note

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

App.tsx

import{ isPlatform, setupIonicReact }from'@ionic/react';

setupIonicReact({
 animated:!isPlatform('mobileweb'),
});

note

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

main.ts

import{ IonicVue, isPlatform }from'@ionic/vue';

createApp(App).use(IonicVue,{
 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:

Angular
React
Vue

app.module.ts

import{ isPlatform, IonicModule }from'@ionic/angular';

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

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

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

App.tsx

import{ isPlatform, setupIonicReact }from'@ionic/react';

constgetConfig=()=>{
let config ={
 animated:false,
};

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

return config;
};

setupIonicReact(getConfig());

main.ts

import{ IonicVue, isPlatform }from'@ionic/vue';

constgetConfig=()=>{
let config ={
 animated:false,
};

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

return config;
};

createApp(App).use(IonicVue,getConfig());

Overrides

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

Angular
React
Vue

app.module.ts

import{ isPlatform, IonicModule }from'@ionic/angular';

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

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

App.tsx

import{ isPlatform, setupIonicReact }from'@ionic/react';

constgetConfig=()=>{
if(isPlatform('hybrid')){
return{
 tabButtonLayout:'label-hide',
};
}

return{
 tabButtonLayout:'icon-top',
};
};

setupIonicReact(getConfig());

main.ts

import{ IonicVue, isPlatform }from'@ionic/vue';

constgetConfig=()=>{
if(isPlatform('hybrid')){
return{
 tabButtonLayout:'label-hide',
};
}

return{
 tabButtonLayout:'icon-top',
};
};

createApp(App).use(IonicVue,getConfig());

Reading the Config (Angular)

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

get

Description Returns a config value as an any. Returns null if the config is not defined.

Signature get(key: string, fallback?: any) => any

Examples

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

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

getBoolean

Description Returns a config value as a boolean. Returns false if the config is not defined.

Signature getBoolean(key: string, fallback?: boolean) => boolean

Examples

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

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

getNumber

Description Returns a config value as a number. Returns 0 if the config is not defined.

Signature getNumber(key: string, fallback?: number) => number

Interfaces

IonicConfig

Below are the config options that Ionic uses.

Config	Type	Description
`actionSheetEnter`	`AnimationBuilder`	Provides a custom enter animation for all `ion-action-sheet`, overriding the default "animation".
`actionSheetLeave`	`AnimationBuilder`	Provides a custom leave animation for all `ion-action-sheet`, overriding the default "animation".
`alertEnter`	`AnimationBuilder`	Provides a custom enter animation for all `ion-alert`, overriding the default "animation".
`alertLeave`	`AnimationBuilder`	Provides a custom leave animation for all `ion-alert`, overriding the default "animation".
`animated`	`boolean`	If `true`, Ionic will enable all animations and transitions across the app.
`backButtonDefaultHref`	`string`	Overrides the default value for the `defaultHref` property in all `<ion-back-button>` components.
`backButtonIcon`	`string`	Overrides the default icon in all `<ion-back-button>` components.
`backButtonText`	`string`	Overrides the default text in all `<ion-back-button>` components.
`innerHTMLTemplatesEnabled`	`boolean`	Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `false`, all `innerHTML` usage will be disabled in Ionic, and custom HTML will not be usable in the relevant components. `innerHTML` usage is enabled by default.
`hardwareBackButton`	`boolean`	If `true`, Ionic will respond to the hardware back button in an Android device.
`infiniteLoadingSpinner`	`SpinnerTypes`	Overrides the default spinner type in all `<ion-infinite-scroll-content>` components.
`loadingEnter`	`AnimationBuilder`	Provides a custom enter animation for all `ion-loading`, overriding the default "animation".
`loadingLeave`	`AnimationBuilder`	Provides a custom leave animation for all `ion-loading`, overriding the default "animation".
`loadingSpinner`	`SpinnerTypes`	Overrides the default spinner for all `ion-loading` overlays.
`menuIcon`	`string`	Overrides the default icon in all `<ion-menu-button>` components.
`menuType`	`string`	Overrides the default menu type for all `<ion-menu>` components.
`modalEnter`	`AnimationBuilder`	Provides a custom enter animation for all `ion-modal`, overriding the default "animation".
`modalLeave`	`AnimationBuilder`	Provides a custom leave animation for all `ion-modal`, overriding the default "animation".
`mode`	`Mode`	The mode determines which platform styles to use for the whole application.
`navAnimation`	`AnimationBuilder`	Overrides the default "animation" of all `ion-nav` and `ion-router-outlet` across the whole application.
`pickerEnter`	`AnimationBuilder`	Provides a custom enter animation for all `ion-picker`, overriding the default "animation".
`pickerLeave`	`AnimationBuilder`	Provides a custom leave animation for all `ion-picker`, overriding the default "animation".
`platform`	`PlatformConfig`	Overrides the default platform detection methods.
`popoverEnter`	`AnimationBuilder`	Provides a custom enter animation for all `ion-popover`, overriding the default "animation".
`popoverLeave`	`AnimationBuilder`	Provides a custom leave animation for all `ion-popover`, overriding the default "animation".
`refreshingIcon`	`string`	Overrides the default icon in all `<ion-refresh-content>` components.
`refreshingSpinner`	`SpinnerTypes`	Overrides the default spinner type in all `<ion-refresh-content>` components.
`rippleEffect`	`boolean`	If `true`, Material Design ripple effects will be enabled across the app.
`sanitizerEnabled`	`boolean`	If `true`, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML.
`spinner`	`SpinnerTypes`	Overrides the default spinner in all `<ion-spinner>` components.
`statusTap`	`boolean`	If `true`, clicking or tapping the status bar will cause the content to scroll to the top.
`swipeBackEnabled`	`boolean`	If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application.
`tabButtonLayout`	`TabButtonLayout`	Overrides the default "layout" of all `ion-bar-button` across the whole application.
`toastDuration`	`number`	Overrides the default `duration` for all `ion-toast` components.
`toastEnter`	`AnimationBuilder`	Provides a custom enter animation for all `ion-toast`, overriding the default "animation".
`toastLeave`	`AnimationBuilder`	Provides a custom leave animation for all `ion-toast`, overriding the default "animation".
`toggleOnOffLabels`	`boolean`	Overrides the default `enableOnOffLabels` in all `ion-toggle` components.

Global Config​

Per-Component Config​

Per-Platform Config​

Fallbacks​

Overrides​

Reading the Config (Angular)​

get​

Examples​

getBoolean​

Examples​

getNumber​

Interfaces​

IonicConfig​

Contents

Global Config

Per-Component Config

Per-Platform Config

Fallbacks

Overrides

Reading the Config (Angular)

get

Examples

getBoolean

Examples

getNumber

Interfaces

IonicConfig