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

example.js

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

Angular

app.module.ts

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

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

Angular (Standalone)

main.ts

import { provideIonicAngular } from '@ionic/angular/standalone';

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular({
      rippleEffect: false,
      mode: 'md'
    })
  ]
})

React

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

Vue

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

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>

Angular

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(...)
class MyComponent {
  /**
   * The back button text can be updated
   * anytime the locale changes.
   */
  backButtonText = 'Go Back';
}

Angular (Standalone)

Not recommended

import { provideIonicAngular } from '@ionic/angular/standalone';

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular({
      // Not recommended when your app requires reactive values
      backButtonText: 'Go Back'
    })
  ]
})

Recommended

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

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

React

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';

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

Vue

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>

<script setup lang="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

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

Angular (Standalone)

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.

main.ts

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

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular({
      animated: !isPlatform('mobileweb')
    })
  ]
})

React

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

Vue

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

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

Angular (Standalone)

main.ts

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

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

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

  return config;
}

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular(getConfig())
  ]
})

React

App.tsx

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

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

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

  return config;
};

setupIonicReact(getConfig());

Vue

main.ts

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

const getConfig = () => {
  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

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

Angular (Standalone)

main.ts

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

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

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

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular(getConfig())
  ]
})

React

App.tsx

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

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

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

setupIonicReact(getConfig());

Vue

main.ts

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

const getConfig = () => {
  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

Angular

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

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

Angular (Standalone)

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

@Component(...)
class AppComponent {
  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

Angular

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

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

Angular (Standalone)

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

@Component(...)
class AppComponent {
  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 true, content passed to the relevant components will be parsed as HTML instead of plaintext. Defaults to false.
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.
experimentalCloseWatcher	boolean	Experimental: 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.
focusManagerPriority	FocusManagerPriority[]	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.