Premiers pas

Bibliothèque de thème CSS/JS qui applique le système de design Material Design 3 aux applications Ionic.

Démonstration : https://ionic-theme-md3.rdlabo.dev/

Conçu pour être compatible avec @rdlabo/ionic-theme-ios26, afin qu’un même arbre de balisage permette de styliser les deux modes Ionic.

Installation

Dans un projet Ionic existant :

npm install @rdlabo/ionic-theme-md3

Remarque : si vous utilisez @ionic/core@ < 8.8.0, utilisez @rdlabo/ionic-theme-md3@1.0.2.

Importez ensuite le thème dans le fichier CSS principal de votre projet, par exemple src/styles.scss.

@import '@rdlabo/ionic-theme-md3/dist/css/default-variables.css';
@import '@rdlabo/ionic-theme-md3/dist/css/ionic-theme-md3.css';

Configurer les animations

Si vous avez installé uniquement le thème MD3, configurez son animation comme suit.

import { isPlatform } from '@ionic/core'; // ou @ionic/angular (Ionic 9), @ionic/angular/standalone (Ionic 8), @ionic/react, @ionic/vue
import { mdTransitionAnimation } from '@rdlabo/ionic-theme-md3';

// Angular
provideIonicAngular({
    ...
    navAnimation: isPlatform('ios') ? undefined: mdTransitionAnimation,
});

// React
setupIonicReact({
    ...
    navAnimation: isPlatform('ios') ? undefined: mdTransitionAnimation,
});

// Vue
createApp(App)
    .use(IonicVue, {
        ...
        navAnimation: isPlatform('ios') ? undefined: mdTransitionAnimation,
})

Vérifier le thème

Testez sur Android. Pour un aperçu sur ordinateur, définissez le mode Ionic sur md dans la configuration d’initialisation actuelle de votre framework, par exemple mode: 'md'.

Utilisez ce balisage pour prévisualiser l’apparence d’une liste groupée en retrait. Consultez Utiliser ion-item-group pour la structure attendue par le thème.

<ion-list mode="md" 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>

Facultatif : associer les thèmes MD3 et iOS 26

Installez le thème iOS 26 pour appliquer les styles aux deux modes Ionic dans la même application.

Les versions actuelles des deux thèmes nécessitent @ionic/core 8.8.1 ou une version ultérieure. Mettez Ionic à niveau avant cette configuration si votre application utilise 8.8.0 ou une version antérieure.

npm install @rdlabo/ionic-theme-ios26

Si votre feuille de style globale utilise Sass, initialisez les thèmes dans cet ordre :

@use '@rdlabo/ionic-theme-ios26/src/styles/default-variables.scss' as ios26-vars;
@use '@rdlabo/ionic-theme-ios26/src/styles/ionic-theme-ios26.scss';
@use '@rdlabo/ionic-theme-ios26/src/styles/ionic-theme-ios26-dark-class.scss';
@use '@rdlabo/ionic-theme-ios26/src/styles/md-remove-ios-class-effect.scss';
@use '@rdlabo/ionic-theme-md3/dist/css/default-variables.css' as md3-vars;
@use '@rdlabo/ionic-theme-md3/dist/css/ionic-theme-md3.css';

L’exemple utilise le mode sombre Ionic activé par classe. Votre feuille de style globale doit également charger la palette sombre Ionic correspondante, par exemple @ionic/angular/css/palettes/dark.class.css pour Angular. Avec dark-system ou dark-always, choisissez la même variante pour la palette Ionic et le thème iOS 26. Consultez la documentation du mode sombre d’Ionic. Les espaces de noms explicites ios26-vars et md3-vars empêchent les deux modules de variables d’utiliser le même espace de noms par défaut.

Configurez les deux implémentations de transition lorsque les deux thèmes sont installés :

import { isPlatform } from '@ionic/core'; // ou @ionic/angular (Ionic 9), @ionic/angular/standalone (Ionic 8), @ionic/react, @ionic/vue
import { iosTransitionAnimation, popoverEnterAnimation, popoverLeaveAnimation } from '@rdlabo/ionic-theme-ios26';
import { mdTransitionAnimation } from '@rdlabo/ionic-theme-md3';

// Angular
provideIonicAngular({
    ...
    navAnimation: isPlatform('ios') ? iosTransitionAnimation : mdTransitionAnimation,
    popoverEnter: isPlatform('ios') ? popoverEnterAnimation : undefined,
    popoverLeave: isPlatform('ios') ? popoverLeaveAnimation : undefined,
});

// React
setupIonicReact({
    ...
    navAnimation: isPlatform('ios') ? iosTransitionAnimation : mdTransitionAnimation,
    popoverEnter: isPlatform('ios') ? popoverEnterAnimation : undefined,
    popoverLeave: isPlatform('ios') ? popoverLeaveAnimation : undefined,
});

// Vue
createApp(App)
    .use(IonicVue, {
        ...
        navAnimation: isPlatform('ios') ? iosTransitionAnimation : mdTransitionAnimation,
        popoverEnter: isPlatform('ios') ? popoverEnterAnimation : undefined,
        popoverLeave: isPlatform('ios') ? popoverLeaveAnimation : undefined,
    });

Documentation

Utiliser ion-item-group — balisage commun des listes en retrait pour iOS 26 et MD3.
Balisage particulier — combinaisons de composants à activer explicitement utilisées dans la démonstration.
ESLint — vérifier la structure des listes avec les règles ESLint.
Migration — changements requis lors de la mise à jour du balisage du thème.

Projets connexes

Si vous avez besoin d’une implémentation plus complète de Material Design 3, ce projet peut aussi vous intéresser :

md3-for-ionic de danielkleebinder

Remarque : ce thème est conçu spécialement pour être compatible avec l’approche de design d’Ionic et @rdlabo/ionic-theme-ios26 ; il ne vise pas à reproduire strictement et intégralement MD3.

Modifier cette page sur GitHub