Theme setup

Give an existing Ionic app the iOS 27 appearance in four steps. This guide uses the iOS 27 theme on its own and system dark mode. For browser-dependent iOS 26/27 styling or MD3, use adaptive themes instead.

Before you start

Use an existing Ionic Angular, React, or Vue application with Ionic >=8.8.1 <10. Keep Ionic's base CSS imports. Browser-only apps do not need a native Capacitor project.

1. Install the theme and Foldable

npm install @rdlabo/ionic-theme-ios27 @erkamyaman/capacitor-foldable

Capacitor Foldable is our standard integration for device state. Its placement and posture APIs let your app control how the layout adapts; installing it is followed by connecting its initial values and change events. Connect it using the layout guide when configuring device layout.

2. Load the styles

Add these imports to your global stylesheet after Ionic's base styles. Replace an existing Ionic dark palette import rather than loading multiple palettes:

@import '@ionic/core/css/palettes/dark.system.css';
@import '@rdlabo/ionic-theme-ios27/dist/css/default-variables.css';
@import '@rdlabo/ionic-theme-ios27/dist/css/ionic-theme-ios27.css';
@import '@rdlabo/ionic-theme-ios27/dist/css/md-remove-ios-class-effect.css';
@import '@rdlabo/ionic-theme-ios27/dist/css/ionic-theme-ios27-dark-system.css';

Choose one dark-mode pair

Use one matching Ionic palette and theme variant. Paths below are relative to @ionic/core/css/palettes/ and @rdlabo/ionic-theme-ios27/dist/css/ respectively.

If you also enable Native UI, these styles provide its light/dark appearance marker. Keep the Ionic palette and theme variant paired so Web and native controls agree. See native appearance inheritance for the resolution order and shared rail behavior.

3. Configure Ionic animations

Set these options in your existing Ionic initialization, before rendering the app:

import { iosTransitionAnimation, popoverEnterAnimation, popoverLeaveAnimation } from '@rdlabo/ionic-theme-ios27';

const ionicConfig = {
  mode: 'ios' as const,
  navAnimation: iosTransitionAnimation,
  popoverEnter: popoverEnterAnimation,
  popoverLeave: popoverLeaveAnimation,
};

This example deliberately uses ios mode so desktop browsers show the theme too. Pass ionicConfig to the initializer your app already uses:

Merge with existing options; do not initialize Ionic twice. To retain Material Design mode on Android, keep your platform-based mode selection and apply these animation options only to the iOS configuration. See adaptive themes for a complete platform-aware example.

4. Preview your first screen

Start your application's usual development server and open an existing page. Add this markup inside its ion-content (use your framework's component syntax):

<ion-list inset="true">
  <ion-item-group>
    <ion-item><ion-label>Notifications</ion-label></ion-item>
    <ion-item><ion-label>Appearance</ion-label></ion-item>
  </ion-item-group>
</ion-list>

You should see an inset group with rounded edges. Switch the system between light and dark appearance, then navigate between pages to see the theme transition. Read Using ion-item-group for list structure.

Next steps

• Customize styles and components.
• Add Native UI for supported controls in a Capacitor iOS app. Theme installation alone does not enable native controls.
• Add Vertical Bars with an existing theme.
• Migrate an existing app.