A Fresh Look at Ionic Global Configuration — IonicConfig Options Explained

When you use Ionic, you run an initialization method for your framework. In Angular that is provideIonicAngular; in React, setupIonicReact; in Vue, inside use on createApp.

Passing arguments there overrides Ionic's initial settings app-wide. Options include enabling or disabling animations, platform style, hardware back button behavior, status bar tap behavior, icon customization, custom animations, security settings, and more.

This article revisits Ionic's global configuration and explains what each option means and how to use it.

How to configure

Angular

provideIonicAngular({
  rippleEffect: false,
  mode: 'md',
})

React

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

Vue

createApp(App).use(IonicVue, {
  rippleEffect: false,
  mode: 'md',
});

IonicConfig in depth — settings to customize your app

Animation and visual effects

• animated?: boolean: Enables or disables animations and transitions app-wide. Default is true. On low-end devices where animations stutter, set false for smoother motion. Balance performance and user experience.

• rippleEffect?: boolean: Enables or disables Material Design ripple effects. Default is true. Disable on low-end devices or when ripples are unnecessary.

Platform and hardware integration

• mode?: Mode: Sets the platform style app-wide: ios, md (Material Design), auto, and others. auto picks based on the device OS. Use this when you want a platform-specific look and feel.

• hardwareBackButton?: boolean: Enables the Android hardware back button. Default is true on mobile. Set false to disable it.

• statusTap?: boolean: Scrolls to the top when the status bar is tapped. Default is true on mobile.

Back button and menu button customization

• backButtonIcon?: string: Overrides the default icon for all <ion-back-button> components. Handy for custom icons.

• backButtonText?: string: Overrides the default text for all <ion-back-button> components.

• backButtonDefaultHref?: string: Overrides the default href for all <ion-back-button> components.

• menuIcon?: string: Overrides the default icon for all <ion-menu-button> components.

• menuType?: string: Overrides the default menu type for all <ion-menu> components. By default it follows the app mode.

Spinner, toggle, and other component defaults

• spinner?: SpinnerTypes: Overrides the default spinner for all <ion-spinner> components. By default it follows the mode (ios or md).

• toggleOnOffLabels?: boolean: Enables or disables default on/off labels for all <ion-toggle> components.

• loadingSpinner?: SpinnerTypes | null: Overrides the default spinner for all ion-loading overlays created by ion-loading-controller.

• refreshingIcon?: string: Overrides the default icon for all <ion-refresh-content> components.

• refreshingSpinner?: SpinnerTypes | null: Overrides the default spinner type for all <ion-refresh-content> components.

• infiniteLoadingSpinner?: SpinnerTypes | null: Overrides the default spinner type for all <ion-infinite-scroll-content> components.

Gestures and navigation

• swipeBackEnabled?: boolean: Enables or disables swipe-to-go-back app-wide. Default is true.

• tabButtonLayout?: TabButtonLayout: Overrides the default layout for all ion-bar-button elements.

Animation customization

navAnimation, actionSheetEnter, alertEnter, loadingEnter, modalEnter, popoverEnter, toastEnter, pickerEnter, actionSheetLeave, alertLeave, loadingLeave, modalLeave, popoverLeave, toastLeave, and pickerLeave customize enter/leave animations for the matching Ionic overlays. Use AnimationBuilder for custom animations. Advanced customization.

Security and other settings

• sanitizerEnabled?: boolean: Enables a basic DOM sanitizer for properties on components that accept custom HTML. Set true for stronger security.

• innerHTMLTemplatesEnabled?: boolean: Enables use of innerHTML. Consider security risks and keep false unless you need it.

• platform?: PlatformConfig: Overrides default platform detection.

• focusManagerPriority?: FocusManagerPriority[]: Moves focus to the right element after page transitions. Improves accessibility. (Experimental.)

• experimentalCloseWatcher?: boolean: Uses the Close Watcher API so Escape and the hardware back button close menus and overlays and handle navigation. (Experimental; requires hardwareBackButton: true.)

• keyboardHeight, inputShims, scrollPadding, inputBlurring, scrollAssist, hideCaretOnScroll, persistConfig, _forceStatusbarPadding, _testing, _zoneGate, _ael, _rel, _ce: Internal settings you normally should not touch directly.

Summary

I hope this helps you understand IonicConfig and build Ionic apps with finer control. Setting each option appropriately improves user experience and performance. For details, see the official documentation.

See you next time.