# Config

URL: https://ionicframework.com/docs/developing/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`](#ionicconfig) interface.

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

**JavaScript**

example.js

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

**Angular**

app.module.ts

```tsx
/*
 * IonicModule is deprecated and will be removed in a future major version.
 * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
 */
import { IonicModule } from '@ionic/angular/lazy';

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

**Angular (Standalone)**

main.ts

```ts
import { provideIonicAngular } from '@ionic/angular';

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

**React**

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

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

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

**Vue**

main.ts

```tsx
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**
```ts
window.Ionic = {
  config: {
    // Not recommended when your app requires reactive values
    backButtonText: 'Go Back',
  },
};
```

**Recommended**
```html
<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**
```ts
/*
 * IonicModule is deprecated and will be removed in a future major version.
 * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
 */
import { IonicModule } from '@ionic/angular/lazy';

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

**Recommended**
```html
<ion-back-button [text]="backButtonText"></ion-back-button>
```

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

**Angular (Standalone)**

**Not recommended**
```ts
import { provideIonicAngular } from '@ionic/angular';

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

**Recommended**
```html
<ion-back-button [text]="backButtonText"></ion-back-button>
```

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

**React**

**Not recommended**
```tsx
import { setupIonicReact } from '@ionic/react';

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

**Recommended**
```tsx
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**
```ts
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**
```html
<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. Refer to the [Angular Platform Documentation](/docs/angular/platform.md) for the types of platforms you can detect.

app.module.ts

```ts
/*
 * IonicModule is deprecated and will be removed in a future major version.
 * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
 */
import { isPlatform, IonicModule } from '@ionic/angular/lazy';

@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. Refer to the [Angular Platform Documentation](/docs/angular/platform.md) for the types of platforms you can detect.

main.ts

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

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

**React**

**Note**

Refer to the [React Platform Documentation](/docs/react/platform.md) for the types of platforms you can detect.

App.tsx

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

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

**Vue**

**Note**

Refer to the [Vue Platform Documentation](/docs/vue/platform.md) for the types of platforms you can detect.

main.ts

```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

```ts
/*
 * IonicModule is deprecated and will be removed in a future major version.
 * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
 */
import { isPlatform, IonicModule } from '@ionic/angular/lazy';

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

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

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

**Angular (Standalone)**

main.ts

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

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

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

  return config;
}

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

**React**

App.tsx

```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

```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

```ts
/*
 * IonicModule is deprecated and will be removed in a future major version.
 * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
 */
import { isPlatform, IonicModule } from '@ionic/angular/lazy';

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

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

**Angular (Standalone)**

main.ts

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

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

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

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

**React**

App.tsx

```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

```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());
```

## Accessing the Mode

In some cases, you may need to access the current Ionic mode programmatically within your application logic. This can be useful for applying conditional behavior, fetching specific assets, or performing other actions based on the active styling mode.

**JavaScript**

```html
<ion-button id="modeButton"></ion-button>

<script>
  const modeButton = document.querySelector('#modeButton');
  const mode = window.Ionic.config.get('mode') || document.documentElement.getAttribute('mode') || 'md';

  modeButton.innerHTML = `Current mode: ${mode}`;
  modeButton.setAttribute('color', mode === 'ios' ? 'secondary' : 'tertiary');
  modeButton.setAttribute('fill', mode === 'ios' ? 'outline' : 'solid');
</script>
```

**Angular**

`src/app/example.component.html`

```html
<ion-button [color]="mode === 'ios' ? 'secondary' : 'tertiary'" [fill]="mode === 'ios' ? 'outline' : 'solid'">
  Current mode: {{ mode }}
</ion-button>
```

`src/app/example.component.ts`

```ts
import { Component } from '@angular/core';
import { Config, IonButton } from '@ionic/angular';

@Component({
  selector: 'app-example',
  templateUrl: './example.component.html',
  imports: [IonButton],
})
export class ExampleComponent {
  mode: string;
  constructor(public config: Config) {
    this.mode = this.config.get('mode');
  }
}
```

**React**

```tsx
import React, { useState, useEffect } from 'react';
import { IonButton } from '@ionic/react';
import { getMode } from '@ionic/core';

function Example() {
  const [mode, setMode] = useState('');

  useEffect(() => {
    const mode = getMode() || 'md';
    setMode(mode);
  }, []);

  const color = mode === 'ios' ? 'secondary' : 'tertiary';
  const fill = mode === 'ios' ? 'outline' : 'solid';

  return (
    <IonButton color={color} fill={fill}>
      Current mode: {mode}
    </IonButton>
  );
}
export default Example;
```

**Vue**

```html
<template>
  <ion-button :color="color" :fill="fill"> Current mode: {{ mode }} </ion-button>
</template>

<script setup>
  import { ref, computed, onMounted } from 'vue';
  import { IonButton } from '@ionic/vue';
  import { getMode } from '@ionic/core';

  const mode = ref('');

  const color = computed(() => (mode.value === 'ios' ? 'secondary' : 'tertiary'));
  const fill = computed(() => (mode.value === 'ios' ? 'outline' : 'solid'));

  onMounted(() => {
    mode.value = getMode() || 'md';
  });
</script>
```

## 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**

```ts
import { Config } from '@ionic/angular/lazy';

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

**Angular (Standalone)**

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

@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**

```ts
import { Config } from '@ionic/angular/lazy';

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

**Angular (Standalone)**

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

@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-select-option`, `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. |
| `logLevel` | `'OFF' \| 'ERROR' \| 'WARN'` | Configures the logging level for Ionic Framework. If `'OFF'`, no errors or warnings are logged. If `'ERROR'`, only errors are logged. If `'WARN'`, errors and warnings are logged. |
| `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. |
| `platform` | [`PlatformConfig`](/docs/angular/platform.md#customizing-platform-detection-functions) | 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](https://github.com/WICG/close-watcher) 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[]`](/docs/developing/managing-focus.md#types) | **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. |