Construir un panel de ajustes personalizado para un tema de WordPress es una tarea que puede extenderse durante semanas. La API de Ajustes de WordPress exige escribir una cantidad enorme de código repetitivo: registro, renderizado de campos, validación, guardado. Y cuando el proyecto está en llamas, escribir todo esto desde cero es un lujo injustificable.

Redux Framework resuelve este problema de forma radical: en lugar de lidiar manualmente con la API de Ajustes, usted describe los campos necesarios en un archivo de configuración y el framework se encarga de todo lo demás: renderizado, validación, escape, importación/exportación e incluso CSS dinámico. En WordPress.org el plugin tiene más de 32 millones de descargas y más de un millón de instalaciones activas, y esto no es inflación de marketing, sino una consecuencia directa de que Redux realmente ahorra semanas de desarrollo.

En esta guía, configuración paso a paso de Redux Framework desde cero hasta un panel de opciones de tema funcional, incluyendo demostración en vivo en el personalizador y uso seguro de los valores guardados en el frontend.

💡 Resumen rápido:

• Instalación de Redux Framework: tres formas de integrarlo en un proyecto WordPress
• Conexión del framework y creación de un archivo de configuración
• Configuración de los argumentos del panel: posición en el menú, personalizador, Google Fonts
• Adición de secciones y campos de entrada mediante la API unificada de Redux
• Extracción de valores guardados en las plantillas del tema con protección contra errores

Qué es Redux Framework y por qué lo necesita

Redux Framework es un framework de opciones gratuito y de código abierto para temas y plugins de WordPress. Está construido sobre la API de Ajustes estándar de WordPress, pero abstrae completamente su complejidad. En lugar de docenas de llamadas a register_setting, add_settings_field y settings_fields, usted escribe un array declarativo en PHP y obtiene un panel de ajustes completamente funcional y adaptable, con 49 tipos de campo para elegir.

Es importante no confundirlo con la biblioteca de JavaScript Redux para gestión de estado; son productos completamente diferentes con el mismo nombre. El framework de WordPress apareció antes que la biblioteca JS.

Capacidades clave que obtiene «de serie»:

• 49 tipos de campo: desde texto simple y casilla de verificación hasta editor ACE, repetidor, Google Maps, ordenador de bloques y deslizador de imágenes;
• Salida CSS automática: para campos de tipografía, color, degradado y espaciado, basta con especificar un selector CSS y el propio Redux generará una hoja de estilos con Google Fonts;
• Integración con el personalizador: el mismo argumento customizer => true, y todo el panel se duplica en el Personalizador de WordPress con vista previa en vivo;
• Importación/exportación de ajustes: herramienta integrada para transferir la configuración entre sitios;
• Compilador: un gancho que se dispara cuando cambia un campo con la bandera compile => true; puede, por ejemplo, recompilar SCSS;
• Validación y escape: cada valor pasa por una sanitización correspondiente al tipo de campo; un campo de texto no aceptará un array, uno numérico filtrará las cadenas.

Desde 2024 el framework se desarrolla bajo el ala de Team Updraft (David Anderson, creador de UpdraftPlus). La versión actual, 4.5.11 (marzo de 2026), tiene compatibilidad total con WordPress 7.0 y PHP 8.5. El proyecto reside en redux.io, la documentación en el sitio de documentación de Redux.

Instalación de Redux Framework

Existen tres formas de añadir Redux a un proyecto. La elección depende de la arquitectura de su tema y de cómo planee distribuirlo.

Como un plugin independiente

Instale Redux Framework desde el directorio de WordPress.org como un plugin normal. Tras la activación, el panel de opciones no aparecerá; el plugin solo proporciona la API. Usted describe todos los ajustes en un archivo de configuración dentro de su tema.

Ventajas: el tema se mantiene ligero (el núcleo del framework no infla el archivo comprimido); el framework se actualiza de forma independiente mediante el mecanismo estándar de WordPress.

Desventajas: su tema requiere la presencia de un plugin de terceros; el usuario necesita instalarlo y activarlo por separado; sin el plugin, el panel de ajustes desaparece y usted debe proporcionar una alternativa segura en el código del tema.

En el núcleo del tema

Copie la carpeta ReduxCore dentro de su tema y conéctela en functions.php. El framework se convierte en parte integral del tema; el usuario no necesita instalar un plugin adicional.

Ventajas: el panel de ajustes parece una parte nativa del tema; el usuario no instala nada adicional.

Desventajas: el tamaño del archivo comprimido del tema aumenta unos 2 MB; cada actualización del framework requiere una actualización del tema por su parte; el plugin Theme Check puede emitir advertencias.

En un plugin dependiente del tema

Enfoque recomendado para temas premium. Cree un plugin complementario independiente para su tema (también es conveniente mantener en él los tipos de contenido personalizados, shortcodes y widgets) e incruste Redux en él. En el functions.php del tema, añada una verificación de la presencia de este plugin mediante TGMPA o un mecanismo similar.

Ventajas: arquitectura limpia (la funcionalidad del tema está separada de la presentación); el framework no infla el archivo comprimido del tema; las actualizaciones del framework no afectan directamente al código del tema.

Desventajas: requiere escribir y mantener un plugin independiente; umbral de entrada ligeramente más alto para otros desarrolladores que vayan a entender el proyecto.

La configuración de Redux no depende del método de instalación; los pasos siguientes son idénticos para cualquier variante.

Configuración general: conexión del framework

Dentro del plugin Redux Framework (o del archivo descargado del sitio oficial de Redux) encuentre la carpeta ReduxCore; contiene todo el núcleo.

Cree una carpeta en su plugin (o tema), por ejemplo optionpanel, y copie en ella el contenido de ReduxCore. Coloque junto a ella un archivo config.php vacío; en él describiremos todas las secciones y campos del panel.

Ahora conecte el framework. En el archivo principal del plugin (o en el functions.php del tema) añada:

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

La comprobación class_exists evita un error fatal si otra parte del sitio ya ha cargado Redux (por ejemplo, a través de un plugin independiente). Si el framework está ausente, el panel de ajustes simplemente no se cargará y el sitio seguirá funcionando.

Después de esto puede proceder a crear secciones y campos.

Creación del panel de opciones

Argumentos del framework

Primero, defina una variable global para almacenar todos los ajustes; la necesitará para extraer los valores en las plantillas del tema:

1
$opt_name = 'mytheme_options';

El prefijo es obligatorio, ya que evita conflictos de nombres con otros plugins que usen Redux. Buena práctica: brandname_themename.

Ahora vamos a construir el array de argumentos. Esta es una configuración mínima funcional:

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 );

Desglose de los argumentos clave:

• menu_type: submenu, el panel aparecerá dentro de la opción de menú «Apariencia»; menu, elemento independiente de nivel superior en el administrador;
• customizer: true habilita la duplicación de todos los campos en el Personalizador de WordPress con vista previa en vivo, el usuario ve los cambios antes de guardarlos;
• dev_mode: actívelo durante el desarrollo (depuración ampliada, importación de demostración), pero desactívelo sin falta antes de la publicación;
• update_notice: siempre false para temas y plugins con Redux integrado, sus usuarios no deben recibir notificaciones sobre actualizaciones del framework por separado de su producto;
• show_import_export: añade una herramienta para transferir todos los ajustes entre sitios con un solo clic.

Consulte la lista completa de más de 40 argumentos en la guía de argumentos.

Adición de secciones y campos

Una sección es un grupo lógico de campos (pestaña en la pantalla de ajustes). Sección mínima:

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
) );

Iconos de sección: Redux 4.x es compatible con los Dashicons integrados de WordPress (lista completa en developer.wordpress.org). Para iconos personalizados use clases CSS de su conjunto de iconos (por ejemplo, Font Awesome).

Cada campo es un array asociativo con las claves obligatorias id, type y title. Ejemplos de tipos de uso común:

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
),

Para crear una subsección añada el argumento 'subsection' => true, el campo aparecerá como una pestaña anidada dentro de la sección principal.

Lista de los 49 tipos con ejemplos de configuración en la sección de tipos de campo de la documentación de Redux.

Uso de opciones en el tema

Redux almacena todos los valores en una variable global, la misma que usted especificó en $opt_name. Para obtener un valor en una plantilla, primero declárela como global. Pero una declaración global directa fuera de una función o acción es una mala práctica. El enfoque correcto:

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 función envoltorio hace dos cosas: evita el aviso de PHP «undefined index» al acceder a una clave inexistente y proporciona un valor de respaldo. En la plantilla, el uso se ve así:

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 el panel de ajustes aún no está configurado (por ejemplo, el usuario activó el tema pero no instaló el plugin dependiente), $mytheme_options será un array vacío, y mytheme_get_option() devolverá silenciosamente $default, sin un montón de advertencias en debug.log.

Para CSS dinámico, use la capacidad integrada de Redux, especifique el argumento output en la configuración del campo:

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

Redux generará e incrustará automáticamente la regla CSS <style>body{background-color:#fff;}</style>, sin una sola línea de código manual.

El proceso de instalación y configuración de campos se muestra claramente en este videotutorial: desde la conexión del framework hasta la creación de la primera sección con selects e interruptores:

⁉️🤔 Preguntas frecuentes

¿En qué se diferencia Redux Framework de Carbon Fields, ACF Options Pages y otras soluciones?

Redux ofrece 49 tipos de campo «listos para usar» (frente a ~25 de Carbon Fields y ~30 de ACF Pro) y se centra específicamente en paneles de ajustes del tema, no en campos de metadatos de entradas. ACF Options Pages es un complemento sobre el motor de metacampos, mientras que Redux se diseñó originalmente para paneles de opciones: importación/exportación integrada, compilador, vista previa en vivo en el personalizador, CSS dinámico con Google Fonts. Carbon Fields es más cercano en espíritu, pero requiere Composer y espacios de nombres, lo cual en varios entornos de alojamiento es una barrera. Conclusión: si ya usa ACF para metacampos, elija ACF Options Pages para no multiplicar entidades; si construye un tema desde cero y necesita un panel de opciones potente, Redux le dará más funcionalidades sin costo adicional.

¿Funciona Redux Framework con temas de bloque (edición completa del sitio)?

Sí, pero con salvedades. Redux muestra el panel de ajustes a través de la interfaz de administración clásica (API de ajustes), no mediante el editor del sitio. Para un enfoque híbrido, tema de bloque más panel Redux para ajustes globales (colores, tipografía, scripts de analíticas), la combinación funciona. A partir de la versión 4.5.11, la integración directa con theme.json no está implementada: los valores deben extraerse en las plantillas mediante mytheme_get_option() e incrustarse como variables CSS. Para un entorno FSE puro donde todos los ajustes deberían residir en el editor del sitio, Redux es redundante; para temas clásicos e híbridos, es una de las mejores opciones.

¿Qué hacer si Redux entra en conflicto con otro plugin que usa esta misma librería?

Este es un problema conocido de «doble inclusión». La comprobación if ( ! class_exists( 'Redux' ) ) antes de require_once garantiza que el framework se cargará exactamente una vez: WordPress ejecuta PHP secuencialmente, y el primer require_once hace que las llamadas posteriores sean inofensivas. Si su tema y un plugin de terceros incluyen Redux, la copia que se inicializó primero cargará, y los paneles de ambos productos seguirán funcionando. Con una diferencia significativa en versiones mayores, es posible la incompatibilidad a nivel de API, lo cual se soluciona actualizando la parte rezagada a la versión actual.

¿Se necesita una licencia para usar Redux Framework en un tema comercial?

No. Redux se distribuye bajo GPLv2, la misma licencia que WordPress. Usted puede incluir libremente el framework en temas y plugins comerciales, venderlos en ThemeForest, distribuirlos a través de su propio sitio. La única restricción de GPLv2, que las obras derivadas también deben estar bajo GPLv2, se aplica al código fuente, no al contenido del sitio del usuario final. Redux Pro (campos adicionales, personalizador extendido, soporte prioritario) es un producto de pago independiente, no requerido para el funcionamiento del framework.

¿Qué hacer si tras una actualización de WordPress el panel de Redux dejó de abrirse?

Escenario: tras una actualización mayor de WP, pantalla en blanco en la página de ajustes del tema. Orden de acciones: primero, verifique que tiene una versión de Redux no inferior a la 4.5.11 (compatibilidad con WP 7.0). Segundo, por un minuto active 'dev_mode' => true y observe la salida de errores PHP en la pantalla de ajustes; Redux en modo desarrollo muestra un registro detallado. Tercero, si el error proviene de un campo específico, compruebe si está usando un tipo obsoleto (search eliminado en Redux 3.x, divide renombrado). La lista actual de campos está siempre en la documentación de Redux.

¿Vale la pena usar Redux Framework en 2026?

Redux Framework es un producto maduro y con soporte activo, respaldado por 32 millones de descargas y una comunidad de más de 270 colaboradores en GitHub. Si usted está construyendo un tema de WordPress clásico o híbrido y necesita un panel de ajustes con un rico conjunto de campos, vista previa en vivo en el personalizador y CSS dinámico, Redux le ahorrará semanas de desarrollo y le dará un resultado que cumple con los estándares de seguridad de WordPress (PHPCS, escapado, validación).

Arquitectónicamente, la mejor manera de integrarlo es externalizar el framework en un plugin de tema dependiente mediante require_once con comprobación class_exists. Esto proporciona una base de código limpia, protección contra conflictos de doble inclusión y una ruta de actualización transparente.

Cuándo no se necesita Redux: está haciendo un tema ligero sin panel de ajustes; trabaja en un entorno FSE puro (tema de bloque con theme.json); ya tiene ACF desplegado con Options Pages para metacampos. En estos casos, incorporar Redux por un solo botón de encendido/apagado es como matar moscas a cañonazos: el framework añadirá ~2 MB al tamaño del tema sin un beneficio proporcional.

Antes de empezar a trabajar, consulte la documentación oficial en el sitio para desarrolladores de Redux y el repositorio en GitHub; allí también puede reportar un error o proponer una funcionalidad. Si necesita ayuda con un tipo de campo o argumento específico, escriba en los comentarios, lo resolveremos juntos.