Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท Components and Theming

Ionic Platform Modes: iOS and Material Design

How Ionic picks iOS or Material Design styling, how to force a mode, write per-platform CSS and code, and detect the platform with isPlatform.

Ionic adapts every component to the device it runs on. On iPhone it looks like iOS: large collapsing titles, centred headers, subtle separators. On Android it follows Material Design: left-aligned titles, ripple effects, elevated shadows. This behaviour is called a mode, and it is applied without any code from you. This lesson explains how modes are chosen, how to override them, and how to write platform-specific CSS and logic.

The two modes

Mode Used on Typical traits
ios iPhone, iPad, and Mac browsers Centred title, back chevron with text, translucent bars
md Android, desktop browsers, everything else Left title, ripple, elevation shadows

md is the default for anything that is not iOS, so desktop Chrome shows Material style.

How the mode is selected

At startup Ionic reads, in order:

  1. the mode config value you supply;
  2. a ?ionic:mode= query parameter (development convenience);
  3. the platform detected from the user agent.
TypeScript
// Force a single look on every device
setupIonicReact({ mode: 'md' });
TypeScript
// Angular
provideIonicAngular({ mode: 'ios' });

Forcing one mode is a legitimate design choice. A brand-heavy app often wants identical visuals on both platforms and picks the mode that suits it. Individual components also accept a mode property, so you can mix them:

HTML
<ion-button mode="ios">iOS-style button anywhere</ion-button>

Use that sparingly: mixing styles confuses users who expect platform conventions.

Platform-specific CSS

Ionic adds a mode class to the host element, so CSS can target them:

CSS
.md ion-toolbar { --min-height: 56px; }
.ios ion-toolbar { --min-height: 44px; }

ion-title.title-md { font-weight: 500; }

The html element receives md or ios, and also classes such as plt-ios, plt-android, plt-mobile, plt-hybrid (running inside Capacitor) and plt-desktop. Platform classes make small tweaks easy:

CSS
.plt-android ion-content { --padding-bottom: 24px; }
.plt-desktop ion-card { max-width: 480px; margin-inline: auto; }

Detecting the platform in code

The isPlatform helper answers questions such as "is this a phone running in Capacitor?":

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

if (isPlatform('ios')) { /* iPhone/iPad/iPod */ }
if (isPlatform('android')) { /* Android devices */ }
if (isPlatform('hybrid')) { /* inside Capacitor/Cordova */ }
if (isPlatform('mobileweb')) { /* mobile browser, not an installed app */ }

console.log(getPlatforms()); // e.g. ['android', 'mobile', 'hybrid']

Common platform names: ios, ipad, iphone, android, phablet, tablet, cordova, capacitor, electron, pwa, mobile, mobileweb, desktop, hybrid.

Prefer feature detection to platform detection whenever you can. Ask "does this API exist?" rather than "is this iOS?". Reserve isPlatform for real UI differences and for deciding whether to call native plugins.

Stand-in: detecting a platform from a user agent

Ionic's real detection is more thorough. This stand-in shows the idea and returns a platform list. It runs in plain JavaScript.

JS Stand-in: simple platform detection

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The mode choice follows from the platform. This stand-in maps platforms to modes and honours an override, as Ionic does:

JS Stand-in: choosing ios or md

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Design with both modes in mind

  • Test both modes. The iOS header is shorter; the Material one has an elevation shadow. Custom colours must work in both.
  • Do not build a back button by hand: ion-back-button shows "Back" with a chevron on iOS and an arrow on Android.
  • Use safe areas. Notches and gesture bars require padding at the top and bottom. Ionic headers and content respect env(safe-area-inset-*) automatically; custom fixed elements need padding-top: var(--ion-safe-area-top).
  • Use the status bar styling plugin to match your theme (chapter 5).
  • Avoid fixed pixel heights for headers, because modes use different heights.

Per-mode theme variables

Ionic components define their variables under mode classes. You can override just one mode:

CSS
.ios ion-item { --border-color: rgba(0, 0, 0, 0.08); }
.md ion-item  { --inner-border-width: 0 0 1px 0; }

This combines with the palette from theming to give you a consistent but platform-respecting design.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which mode does a desktop Chrome browser use by default?

    md is the default for anything that is not iOS.
  2. 2. How do you force Material style on every device?

    Pass mode: 'md' when initialising Ionic, or set mode on individual components.
  3. 3. What does isPlatform('hybrid') test?

    hybrid means the app runs in a native shell rather than a plain browser.
  4. 4. Why prefer feature detection over platform detection?

    Checking for a capability is more robust than guessing from the device name.

Summary

  • Ionic applies ios or md styling automatically; md is the default off iOS.
  • Force a mode through config, the mode property or ?ionic:mode=.
  • Target modes with .ios and .md CSS selectors and plt-* platform classes.
  • isPlatform() and getPlatforms() answer questions in code; prefer feature detection.
  • Respect safe areas and test both modes.

Next: Layout, Grid and Utilities