Créer un panneau de paramètres personnalisé pour un thème WordPress est une tâche qui peut s’étaler sur des semaines. L’API Settings de WordPress impose d’écrire une quantité considérable de code répétitif: enregistrement, affichage des champs, validation, sauvegarde. Et quand le projet est sous tension, écrire tout cela from scratch est un luxe injustifiable.

Redux Framework résout ce problème de manière radicale: au lieu de vous débattre manuellement avec l’API Settings, vous décrivez les champs nécessaires dans un seul fichier de configuration, et le framework prend en charge tout le reste: l’affichage, la validation, l’échappement, l’import/export et même le CSS dynamique. Sur WordPress.org, l’extension totalise plus de 32 millions de téléchargements et plus d’un million d’installations actives, et ce n’est pas une inflation marketing, mais la conséquence directe du fait que Redux fait réellement gagner des semaines de développement.

Dans ce guide, nous allons voir la mise en place pas à pas de Redux Framework, de zéro jusqu’à un panneau d’options de thème fonctionnel, avec une démonstration en direct dans le personnalisateur et une utilisation sécurisée des valeurs sauvegardées en frontend.

💡 Aperçu rapide:

• Installer Redux Framework: trois façons de l’intégrer dans un projet WordPress
• Connecter le framework et créer un fichier de configuration
• Configurer les arguments du panneau: position dans le menu, personnalisateur, Google Fonts
• Ajouter des sections et des champs de saisie via l’API unifiée de Redux
• Extraire les valeurs sauvegardées dans les templates du thème avec une protection contre les erreurs

Qu’est-ce que Redux Framework et pourquoi vous en avez besoin

Redux Framework est un framework d’options gratuit et open source pour les thèmes et extensions WordPress. Il est construit au-dessus de l’API Settings standard de WordPress, mais il en abstrait totalement la complexité. Au lieu de dizaines d’appels à register_setting, add_settings_field et settings_fields, vous écrivez un tableau déclaratif en PHP et vous obtenez un panneau de paramètres entièrement fonctionnel, responsive, avec 49 types de champs au choix.

Il est important de ne pas le confondre avec la bibliothèque JavaScript Redux pour la gestion d’état: ce sont des produits complètement différents qui portent le même nom. Le framework WordPress est apparu avant la bibliothèque JS.

Les principales capacités dont vous disposez «out of the box»:

• 49 types de champs: du simple champ texte et case à cocher jusqu’à l’éditeur ACE, le répéteur, Google Maps, le trieur de blocs et le slider d’images;
• Sortie CSS automatique: pour les champs de typographie, couleur, dégradé, espacement, il suffit de spécifier un sélecteur CSS et Redux génère lui-même une feuille de styles avec les Google Fonts;
• Intégration au personnalisateur: le seul argument customizer => true, et tout le panneau est dupliqué dans le Personnalisateur WordPress avec un aperçu en direct;
• Import/export des paramètres: un outil intégré pour transférer la configuration entre sites;
• Compilateur: un hook qui se déclenche lorsqu’un champ avec le flag compile => true change, ce qui permet par exemple de recompiler du SCSS;
• Validation et échappement: chaque valeur passe par une assainissement correspondant au type de champ, un champ texte n’acceptera pas un tableau, un champ numérique filtrera les chaînes.

Depuis 2024, le framework est développé sous l’égide de l’équipe Updraft (David Anderson, créateur d’UpdraftPlus). La version actuelle, 4.5.11 (mars 2026), est entièrement compatible avec WordPress 7.0 et PHP 8.5. Le projet vit sur redux.io, la documentation sur le site de documentation Redux.

Installer Redux Framework

Il existe trois façons d’ajouter Redux à un projet. Le choix dépend de l’architecture de votre thème et de la manière dont vous prévoyez de le distribuer.

En tant qu’extension séparée

Installez Redux Framework depuis le répertoire WordPress.org comme une extension classique. Après activation, le panneau d’options n’apparaît pas, l’extension fournit uniquement l’API. Vous décrivez tous les paramètres dans un fichier de configuration à l’intérieur de votre thème.

Avantages: le thème reste léger (le cœur du framework n’alourdit pas l’archive); le framework se met à jour indépendamment via le mécanisme standard de WordPress.

Inconvénients: votre thème nécessite la présence d’une extension tierce, l’utilisateur doit l’installer et l’activer séparément; sans l’extension, le panneau de paramètres disparaît, et vous devez prévoir une solution de repli gracieuse dans le code du thème.

Dans le cœur du thème

Copiez le dossier ReduxCore à l’intérieur de votre thème et connectez-le dans functions.php. Le framework devient une partie intégrante du thème, l’utilisateur n’a pas besoin d’installer d’extension supplémentaire.

Avantages: le panneau de paramètres apparaît comme une partie native du thème, l’utilisateur n’installe rien de plus.

Inconvénients: la taille de l’archive du thème augmente d’environ 2 Mo; chaque mise à jour du framework nécessite une mise à jour du thème de votre part; l’extension Theme Check peut émettre des avertissements.

Dans une extension de thème dépendante

C’est l’approche recommandée pour les thèmes premium. Créez une extension compagnon distincte pour votre thème (c’est aussi pratique pour y conserver les types de publication personnalisés, les shortcodes, les widgets) et intégrez-y Redux. Dans le functions.php du thème, ajoutez une vérification de la présence de cette extension via TGMPA ou un mécanisme similaire.

Avantages: architecture propre (la fonctionnalité du thème est séparée de la présentation); le framework n’alourdit pas l’archive du thème; les mises à jour du framework n’affectent pas directement le code du thème.

Inconvénients: nécessite d’écrire et de maintenir une extension séparée; barrière d’entrée légèrement plus élevée pour les autres développeurs qui découvriront le projet.

La configuration de Redux ne dépend pas de la méthode d’installation, les étapes suivantes sont identiques quel que soit le variant choisi.

Configuration générale: connecter le framework

Dans l’extension Redux Framework (ou dans l’archive téléchargée depuis le site officiel de Redux), repérez le dossier ReduxCore, il contient tout le cœur.

Créez un dossier dans votre extension (ou votre thème), par exemple optionpanel, et copiez-y le contenu de ReduxCore. Placez un fichier config.php vide à côté, nous y décrirons toutes les sections et tous les champs du panneau.

Maintenant, connectez le framework. Dans le fichier principal de l’extension (ou le functions.php du thème), ajoutez:

1
<?php
2
if ( ! class_exists( 'Redux' ) ) {
3
    require_once plugin_dir_path( __FILE__ ) . 'optionpanel/ReduxCore/framework.php';
4
}

La vérification class_exists évite une erreur fatale si une autre partie du site a déjà chargé Redux (par exemple, via un plugin distinct). Si le framework est absent, le panneau de paramètres ne se chargera tout simplement pas et le site continuera de fonctionner.

Après cela, vous pouvez passer à la création des sections et des champs.

Création du panneau d'options

Arguments du framework

Tout d'abord, définissez une variable globale pour stocker tous les paramètres, elle sera nécessaire pour extraire les valeurs dans les templates du thème:

1
$opt_name = 'mytheme_options';

Le préfixe est obligatoire, il évite les conflits de noms avec d'autres plugins utilisant Redux. Bonne pratique: brandname_themename.

Assemblons maintenant le tableau d'arguments. Voici une configuration minimale fonctionnelle:

1
$args = array(
2
    'opt_name'             => $opt_name,
3
    'display_name'         => 'Theme Settings',
4
    'display_version'      => '1.0.0',
5
    'menu_type'            => 'submenu',
6
    'allow_sub_menu'       => true,
7
    'menu_title'           => 'Theme Settings',
8
    'page_title'           => 'Theme Settings Panel',
9
    'page_parent'          => 'themes.php',
10
    'page_permissions'     => 'manage_options',
11
    'page_slug'            => 'theme_options',
12
    'dev_mode'             => false,
13
    'update_notice'        => false,
14
    'customizer'           => true,
15
    'save_defaults'        => true,
16
    'show_import_export'   => true,
17
    'async_typography'     => true,
18
    'admin_bar'            => true,
19
    'global_variable'      => $opt_name,
20
);
21
 
22
Redux::set_args( $opt_name, $args );

Détail des arguments clés:

• menu_type: submenu, le panneau apparaîtra dans l'élément de menu «Apparence»; menu, un élément de premier niveau distinct dans l'administration;
• customizer: true active la duplication de tous les champs dans l'outil de personnalisation WordPress avec aperçu en direct, l'utilisateur voit les modifications avant de les enregistrer;
• dev_mode: à activer pendant le développement (débogage étendu, importation de démo), mais à désactiver impérativement avant la mise en production;
• update_notice: toujours false pour les thèmes et plugins qui embarquent Redux, vos utilisateurs ne doivent pas recevoir de notifications de mise à jour du framework indépendamment de votre produit;
• show_import_export: ajoute un outil pour transférer tous les paramètres entre sites en un clic.

Pour la liste complète de plus de 40 arguments, consultez le guide des arguments.

Ajout de sections et de champs

Une section est un groupe logique de champs (onglet sur l'écran des paramètres). Section minimale:

1
Redux::set_section( $opt_name, array(
2
    'title'  => 'Site Header',
3
    'id'     => 'header_section',
4
    'icon'   => 'dashicons-heading',
5
    'fields' => array(
6
        array(
7
            'id'       => 'header_logo',
8
            'type'     => 'media',
9
            'title'    => 'Logo',
10
            'subtitle' => 'Upload logo image',
11
            'default'  => array( 'url' => get_template_directory_uri() . '/images/logo.png' ),
12
        ),
13
        array(
14
            'id'      => 'sticky_header',
15
            'type'    => 'switch',
16
            'title'   => 'Sticky Header',
17
            'default' => true,
18
        ),
19
    ),
20
) );

Icônes de section: Redux 4.x prend en charge les Dashicons natives de WordPress (liste complète sur developer.wordpress.org). Pour des icônes personnalisées, utilisez les classes CSS de votre jeu d'icônes (par exemple, Font Awesome).

Chaque champ est un tableau associatif avec les clés obligatoires id, type et title. Exemples de types couramment utilisés:

1
// Select with search
2
array(
3
    'id'      => 'sidebar_layout',
4
    'type'    => 'select',
5
    'title'   => 'Sidebar Layout',
6
    'options' => array(
7
        'right' => 'Sidebar Right',
8
        'left'  => 'Sidebar Left',
9
        'none'  => 'No Sidebar',
10
    ),
11
    'default' => 'right',
12
),
13
 
14
// RGBA color picker
15
array(
16
    'id'      => 'accent_color',
17
    'type'    => 'color_rgba',
18
    'title'   => 'Accent Color',
19
    'default' => array(
20
        'color' => '#2271b1',
21
        'alpha' => 1,
22
    ),
23
),
24
 
25
// Typography with Google Fonts
26
array(
27
    'id'          => 'body_typography',
28
    'type'        => 'typography',
29
    'title'       => 'Text Font',
30
    'google'      => true,
31
    'font-backup' => true,
32
    'line-height' => true,
33
    'font-size'   => true,
34
    'default'     => array(
35
        'font-family' => 'Inter',
36
        'font-size'   => '16px',
37
    ),
38
),

Pour créer une sous-section, ajoutez l'argument 'subsection' => true, le champ apparaîtra comme un onglet imbriqué à l'intérieur de la section parente.

La liste des 49 types avec des exemples de configuration se trouve dans la section types de champs de la documentation Redux.

Utilisation des options dans le thème

Redux stocke toutes les valeurs dans une variable globale, celle que vous avez indiquée dans $opt_name. Pour récupérer une valeur dans un template, déclarez-la d’abord comme globale. Mais une déclaration global directe en dehors d’une fonction ou d’une action est une mauvaise pratique. La bonne approche:

1
function mytheme_get_option( $option_id, $default = '' ) {
2
    global $mytheme_options;
3
    return isset( $mytheme_options[ $option_id ] ) ? $mytheme_options[ $option_id ] : $default;
4
}

La fonction wrapper fait deux choses: elle évite la notice PHP «undefined index» lorsqu’on accède à une clé inexistante et fournit une valeur de repli. Dans le template, l’utilisation ressemble à ceci:

1
$logo = mytheme_get_option( 'header_logo' );
2
if ( ! empty( $logo['url'] ) ) {
3
    echo '<img src="' . esc_url( $logo['url'] ) . '" alt="' . esc_attr( get_bloginfo( 'name' ) ) . '">';
4
}

Si le panneau de réglages n’est pas encore configuré (par exemple, l’utilisateur a activé le thème mais n’a pas installé le plugin dépendant), $mytheme_options sera un tableau vide et mytheme_get_option() retournera silencieusement $default, sans accumuler les avertissements dans debug.log.

Pour le CSS dynamique, utilisez la capacité intégrée de Redux en spécifiant l’argument output dans la configuration du champ:

1
array(
2
    'id'     => 'body_bg_color',
3
    'type'   => 'color',
4
    'title'  => 'Background Color',
5
    'output' => array( 'background-color' => 'body' ),
6
),

Redux générera et intégrera automatiquement la règle CSS <style>body{background-color:#fff;}</style>, sans une seule ligne de code manuel.

Le processus d’installation et de configuration des champs est clairement montré dans ce tutoriel vidéo: de la connexion du framework à la création de la première section avec des listes déroulantes et des interrupteurs:

⁉️🤔 Foire aux questions

En quoi Redux Framework se distingue-t-il de Carbon Fields, ACF Options Pages et des autres solutions?

Redux propose 49 types de champs «prêts à l’emploi» (contre environ 25 pour Carbon Fields et environ 30 pour ACF Pro) et se concentre spécifiquement sur les panneaux de réglages de thème, pas sur les champs de métadonnées de publication. ACF Options Pages est un module complémentaire greffé sur le moteur de métadonnées, tandis que Redux a été conçu dès le départ pour les panneaux d’options: import/export intégré, compilateur, aperçu en direct dans le personnalisateur, CSS dynamique avec Google Fonts. Carbon Fields est plus proche dans l’esprit, mais nécessite Composer et les espaces de noms, ce qui constitue un obstacle dans un certain nombre d’environnements d’hébergement. Conclusion: si vous utilisez déjà ACF pour les métadonnées, prenez ACF Options Pages pour éviter de multiplier les entités; si vous construisez un thème de toutes pièces et avez besoin d’un panneau d’options puissant, Redux vous apportera plus de fonctionnalités gratuitement.

Redux Framework fonctionne-t-il avec les thèmes en blocs (Full Site Editing)?

Oui, mais avec des réserves. Redux affiche le panneau de réglages via l’interface d’administration classique (Settings API), pas via l’éditeur de site. Pour une approche hybride, thème en blocs plus panneau Redux pour les réglages globaux (couleurs, typographie, scripts d’analytics), la combinaison fonctionne. À partir de la version 4.5.11, l’intégration directe avec theme.json n’est pas implémentée: les valeurs doivent être extraites dans les templates via mytheme_get_option() et intégrées en ligne sous forme de variables CSS. Pour un environnement FSE pur où tous les réglages doivent résider dans l’éditeur de site, Redux est redondant; pour les thèmes classiques et hybrides, c’est l’une des meilleures options.

Que faire si Redux entre en conflit avec un autre plugin utilisant cette même bibliothèque?

C’est un problème connu de «double inclusion». La vérification if ( ! class_exists( 'Redux' ) ) avant require_once garantit que le framework se chargera exactement une fois: WordPress exécute le PHP de manière séquentielle, et le tout premier require_once rend les appels suivants inoffensifs. Si votre thème et un plugin tiers embarquent tous les deux Redux, la copie qui s’est initialisée en premier se chargera, et les panneaux des deux produits continueront de fonctionner. En cas d’écart important de versions majeures, une incompatibilité au niveau de l’API est possible, corrigée en mettant à jour le côté le moins à jour vers la version actuelle.

Faut-il une licence pour utiliser Redux Framework dans un thème commercial?

Non. Redux est distribué sous licence GPLv2, la même que WordPress. Vous pouvez librement inclure le framework dans des thèmes et plugins commerciaux, les vendre sur ThemeForest, les distribuer via votre propre site. La seule restriction de la GPLv2, les travaux dérivés doivent aussi être sous GPLv2, mais cette exigence s’applique au code source, pas au contenu du site de l’utilisateur final. Redux Pro (champs supplémentaires, personnalisateur étendu, support prioritaire) est un produit payant distinct, non requis pour le fonctionnement du framework.

Que faire si, après une mise à jour de WordPress, le panneau Redux ne s’ouvre plus?

Scénario: après une mise à jour majeure de WP, écran blanc sur la page des réglages du thème. Ordre des actions: premièrement, vérifiez que vous disposez d’une version de Redux au moins égale à 4.5.11 (compatibilité avec WP 7.0). Deuxièmement, activez pendant une minute 'dev_mode' => true et regardez la sortie d’erreur PHP sur l’écran des réglages, Redux en mode développement affiche un journal détaillé. Troisièmement, si l’erreur provient d’un champ spécifique, vérifiez si vous utilisez un type obsolète (search supprimé dans Redux 3.x, divide renommé). La liste actuelle des champs se trouve toujours dans la documentation Redux.

Redux Framework vaut-il la peine d’être utilisé en 2026

Redux Framework est un produit mature et activement maintenu, derrière lequel se trouvent 32 millions de téléchargements et une communauté de plus de 270 contributeurs sur GitHub. Si vous construisez un thème WordPress classique ou hybride et avez besoin d’un panneau de réglages avec un riche ensemble de champs, un aperçu en direct dans le personnalisateur et du CSS dynamique, Redux vous fera gagner des semaines de développement et vous donnera un résultat conforme aux normes de sécurité WordPress (PHPCS, échappement, validation).

Sur le plan architectural, la meilleure façon d’intégrer est d’externaliser le framework dans un plugin dépendant du thème via require_once avec vérification class_exists. Cela donne à la fois une base de code propre, une protection contre les conflits de double inclusion et un chemin de mise à jour transparent.

Quand Redux n’est pas nécessaire: vous réalisez un thème léger sans panneau de réglages; vous travaillez dans un environnement FSE pur (thème en blocs avec theme.json); vous avez déjà ACF déployé avec Options Pages pour les métadonnées. Dans ces cas, embarquer Redux pour un seul bouton marche/arrêt, c’est comme tirer sur des moineaux au canon: le framework ajoutera environ 2 Mo à la taille du thème sans bénéfice proportionnel.

Avant de commencer à travailler, consultez la documentation officielle sur le site des développeurs Redux et le dépôt sur GitHub, vous pouvez également y signaler un bug ou proposer une fonctionnalité. Si vous avez besoin d’aide avec un type de champ ou un argument spécifique, écrivez en commentaires, nous trouverons la solution ensemble.