Cuando trabajas en proyectos profesionales con WordPress, tarde o temprano, surge la necesidad de gestionar una biblioteca de iconos SVG. Si además formas parte de un equipo en el que diseño y desarrollo deben ir de la mano, contar con un Design System unificado es casi obligatorio para mantener consistencia, escalabilidad y velocidad en el trabajo.
Durante mucho tiempo, añadir iconos personalizados en WordPress era un proceso engorroso: plugins limitados, configuraciones poco flexibles o tener que editar manualmente archivos JS para cada nuevo icono. Una auténtica pesadilla si trabajas con decenas o cientos de SVG.
La buena noticia es que, con Advanced Custom Fields (ACF) y su campo Icon Picker, ahora es posible integrar tu propia carpeta de iconos personalizados directamente en el panel de WordPress. Esto significa que cualquier miembro del equipo puede seleccionar iconos de forma visual, ordenada y sencilla, sin necesidad de tocar código ni memorizar nombres de archivo.
En este artículo te voy a contar, paso a paso, cómo en Bubuku implementamos iconos personalizados con ACF dentro de proyectos reales, enlazados a su propio Design System, para que tengas una solución escalable y práctica en tu día a día como desarrollador.
Qué problemas hay al integrar iconos personalizados en WordPress
Si alguna vez has intentado añadir tu propia biblioteca de iconos SVG en WordPress, sabrás que no es tan sencillo como parece. Estos son algunos de los problemas más habituales que solemos encontrar:
- Plugins limitados: muchos están pensados para casos simples y no permiten escalar cuando necesitas integrar un Design System completo con decenas o cientos de iconos.
- Carga manual de SVG: en varias soluciones tienes que subir los iconos uno por uno o incrustarlos en archivos JS, lo que se convierte en una tarea repetitiva y difícil de mantener.
- Shortcodes y bloques poco prácticos: algunas herramientas obligan a insertar iconos mediante shortcodes largos o bloques poco flexibles, perdiendo agilidad en el flujo de trabajo.
- Falta de vista previa en el backend: en muchos casos, ni siquiera ves qué icono estás seleccionando hasta que lo publicas, lo que genera errores y ralentiza al equipo.
En Bubuku llegamos a probar The Icon Block, un plugin muy bien diseñado por Nick Diego que encaja perfectamente en el editor de bloques. Sin embargo, cuando necesitas trabajar con iconografías extensas y personalizadas, la gestión se complica: hay que mantener un archivo JS con todos los SVG y actualizarlo cada vez que entra uno nuevo, tal como indica su documentación.
const customIcons = [
{ ... },
{
isDefault: false,
name: 'heart',
title: __( 'Heart', 'custom-icons' ),
icon: '<svg width="24px" height="24px" viewBox="0 0 24 24"><path d="..."></path></svg>',
categories: [ 'category-one' ],
keywords: [ 'love' ],
hasNoIconFill: false,
},
{ ... },
];Aunque la IA puede ayudarte a generar ese archivo automáticamente (como conté en mi perfil de LinkedIn), la experiencia nos dice que es un método demasiado técnico para algo tan cotidiano como elegir un icono.
El resultado es excelente —puedes ver un ejemplo de cómo se gestionan los iconos del Design System en WordPress con The Icon Block en este caso real—, pero sigue siendo una pena que ACF no lo tomara como referencia desde el principio, porque habría ahorrado muchos dolores de cabeza.
Por qué ACF es la mejor opción para iconos SVG en WordPress
Cuando hablamos de proyectos profesionales en WordPress, hay un plugin que rara vez falta: Advanced Custom Fields (ACF). Su popularidad no es casualidad: permite crear campos personalizados de forma flexible y potente, y lo mejor es que los clientes pueden gestionarlos fácilmente desde el panel sin tocar código.
Desde la versión 6.3.0, ACF incorporó un tipo de campo nuevo llamado Icon Picker. Y aquí está la clave: este campo permite seleccionar iconos de forma visual y ordenada directamente desde el backend de WordPress.
Por defecto, ACF Icon Picker soporta iconos de:
- Dashicons
- Biblioteca de medios
- URLs externas
- Carpetas personalizadas de iconos SVG (la parte más interesante)
Este último punto es lo que realmente marca la diferencia para quienes trabajamos con Design Systems. En lugar de depender de plugins limitados o de procesos manuales, ahora podemos tener una carpeta de iconos SVG personalizada, accesible desde un selector visual en el editor.
La gran ventaja es que no importa si eres desarrollador, diseñador o editor de contenido: todos pueden trabajar con la misma biblioteca de iconos, sin necesidad de recordar nombres de archivos o rutas. Esto convierte a ACF en una solución más escalable, intuitiva y profesional para gestionar iconos personalizados en WordPress.
A
Cómo crear una carpeta de iconos en ACF paso a paso
La idea es añadir una pestaña propia en el Icon Picker mediante el filtro acf/fields/icon_picker/tabs y, después, registrar los SVG de tu sistema de diseño con el filtro acf/fields/icon_picker/{tu_slug}/icons. Así consigues un selector visual con iconos dentro de ACF totalmente alineado con tu biblioteca.
Crear la pestaña personalizada (tu “carpeta” de iconos)
Añade este snippet (plugin de funcionalidades, o functions.php del tema hijo). Crea una pestaña llamada Iconography custom accesible desde el selector visual:
add_filter( 'acf/fields/icon_picker/tabs', 'prefix_add_icon_picker_folder' );
function prefix_add_icon_picker_folder( $tabs ) {
$tabs['iconography_custom'] = esc_html__( 'Iconography custom', 'text_domain' );
return $tabs;
}El índice iconography_custom es el slug interno de tu pestaña. Es importante fijarlo desde el principio porque lo reutilizarás en el siguiente filtro para inyectar los iconos SVG. El texto visible (“Iconography custom”) es el texto que verán editores y diseñadores en el CMS.
Insertar los SVG del sistema de diseño en WordPress con ACF
Una vez que tienes la carpeta configurada, toca registrar en ACF qué iconos deben mostrarse dentro de esa pestaña. Para ello usamos el filtro acf/fields/icon_picker/iconography_custom/icons, donde «iconography_custom» coincide con el slug definido arriba:
// 2) Registrar los SVG del Design System en la pestaña personalizada
add_filter( 'acf/fields/icon_picker/iconography_custom/icons', 'prefix_add_icons' );
function prefix_add_icons( $icons ) {
// Carpeta pública donde sirves los SVG de tu Design System
$base_url = get_stylesheet_directory_uri() . '/assets/img/icons/';
return array(
array(
'key' => 'icon-activity', // identificador único
'label' => esc_html__( 'Activity', 'text_domain' ), // nombre legible en el selector
'url' => $base_url . 'activity.svg' // URL absoluta al SVG
),
array(
'key' => 'icon-bolt',
'label' => esc_html__( 'Bolt', 'text_domain' ),
'url' => $base_url . 'bolt.svg'
),
);
}
Hay tres puntos clave que debes cuidar en este snippet: primero, get_stylesheet_directory_uri() es la opción adecuada si trabajas con tema hijo; si lo haces en el tema padre, usa get_template_directory_uri(). Segundo, los keys como icon-activity te ayudan a mantener una nomenclatura consistente con el Design System (evita duplicados y facilita búsquedas). Tercero, la URL debe apuntar a un SVG accesible públicamente; si actualizas un icono y no lo ves reflejado, limpia la caché del servidor o CDN y prueba la URL directa del archivo en el navegador.
Como pauta de estructura, guarda los recursos en un árbol predecible dentro del tema para que cualquier miembro del equipo se oriente rápido:
/wp-content/themes/tu-tema-hijo/
└── assets/
└── img/
└── icons/
├── activity.svg
└── bolt.svgPara mantener todo ordenado, lo ideal es que tus SVG estén limpios (sin metadatos innecesarios) y bien nombrados, de modo que el tema pueda controlar fácilmente su color y tamaño. Con los dos filtros que hemos visto —acf/fields/icon_picker/tabs y acf/fields/icon_picker/{slug}/icons— ya tendrás en el backend un selector visual de iconos SVG personalizados totalmente integrado con tu Design System.
Estos iconos se visualizan directamente en la administración de WordPress, y el usuario puede seleccionarlos desde el selector visual de ACF sin tener que escribir rutas ni memorizar nombres de archivo. Para mí, este fue el cambio radical que convirtió a ACF en la opción preferida en Bubuku a la hora de gestionar iconos en nuestros proyectos con Design System.
Cómo añadir iconos del Design System de forma automática al selector visual de ACF
En el ejemplo anterior solo añadimos dos iconos para probar que todo funcionaba. Sin embargo, en un Design System real lo normal es que tengas decenas o incluso cientos de SVG organizados por categorías (acciones, navegación, alertas, etc.).
La buena noticia es que el filtro acf/fields/icon_picker/{slug}/icons es muy flexible. Puedes generar el listado de iconos de forma dinámica recorriendo la carpeta de SVG y construyendo el array automáticamente, en lugar de escribir cada icono a mano. Así, cada vez que añadas un nuevo SVG en la carpeta, aparecerá disponible en el selector visual de ACF sin tener que modificar el código.
Por ejemplo, podrías recorrer los archivos de «/assets/img/icons/» con scandir() en PHP y generar el array a partir de sus nombres:
// Generar automáticamente la lista de iconos desde la carpeta del Design System
add_filter( 'acf/fields/icon_picker/iconography_custom/icons', 'prefix_load_icons_dynamic' );
function prefix_load_icons_dynamic( $icons ) {
$base_path = get_stylesheet_directory() . '/assets/img/icons/';
$base_url = get_stylesheet_directory_uri() . '/assets/img/icons/';
if ( !is_dir( $base_path ) ) {
return $icons;
}
$files = scandir( $base_path );
foreach ( $files as $file ) {
if ( pathinfo( $file, PATHINFO_EXTENSION ) === 'svg' ) {
$filename = pathinfo( $file, PATHINFO_FILENAME );
$icons[] = array(
'key' => 'icon-' . $filename,
'label' => ucfirst( str_replace( '-', ' ', $filename ) ),
'url' => $base_url . $file
);
}
}
return $icons;
}De esta manera, tu selector siempre estará sincronizado con la carpeta del sistema de diseño sin necesidad de mantenimiento manual. Solo subes el nuevo SVG al directorio, y ACF lo mostrará automáticamente en el backend de WordPress.
Este pequeño truco supone un gran avance en proyectos grandes, porque mantiene la biblioteca de iconos centralizada y fácil de escalar, justo como debe ser en un entorno profesional.
Mostrar iconos SVG personalizados en plantillas y bloques de WordPress con ACF
Hasta ahora hemos creado una carpeta de SVG, la hemos conectado con el Icon Picker de ACF y hemos visto cómo añadir iconos automáticamente desde el Design System. El siguiente paso es usarlos en el frontend de WordPress, ya sea en plantillas o dentro de bloques personalizados.
Mostrar un icono en una plantilla de WordPress
El campo de ACF guarda normalmente el nombre del icono que has seleccionado en el backend. Ese valor lo puedes usar de dos formas: como string (solo el nombre del icono, por ejemplo icon-activity) o como array (nombre de la carpeta y nombre del fichero).
En este ejemplo lo mantenemos sencillo: partimos del nombre del fichero y construimos la ruta al SVG dentro de la carpeta de tu Design System.
/**
* Convierte la clave guardada por ACF en una URL de tu carpeta de iconos.
*/
function prefix_get_icon_url_from_name( $icon_name ) {
if ( ! $icon_name ) return '';
$filename = sanitize_title( $icon_name );
$base_url = get_stylesheet_directory_uri() . '/assets/img/icons/';
return $base_url . $filename . '.svg';
}
// Ejemplo de uso en una plantilla
$icon_name = get_field( 'custom_icon' );
$icon_url = prefix_get_icon_url_from_name( $icon_name );
if ( $icon_url ) {
echo '<img src="' . esc_url( $icon_url ) . '" alt="" loading="lazy" decoding="async" />';
}De esta manera, si mañana cambias de carpeta de iconos, solo actualizas la función y todo el tema seguirá funcionando sin problemas.
Usar iconos en un bloque de WordPress
Si trabajas con bloques personalizados, puedes aprovechar la misma lógica dentro del render_callback del bloque:
function prefix_render_custom_block( $block ) {
$icon_name = get_field( 'custom_icon' );
$icon_url = prefix_get_icon_url_from_name( $icon_name );
if ( $icon_url ) {
echo '<div class="prefix-block-icon">';
echo '<img src="' . esc_url( $icon_url ) . '" alt="" loading="lazy" decoding="async" />';
echo '</div>';
}
}Esto permite que el bloque muestre el icono elegido desde ACF tanto en el editor como en el frontend, integrando tu Design System de forma coherente en WordPress.
Aunque aquí lo mostramos como imagen para mantener la explicación simple, el verdadero potencial está en usar el SVG inline para controlar color y estilos con CSS. Eso lo dejaremos para otra ocasión.
Aquí podemos ver en acción cómo se comporta dentro de un bloque de ACF cuando usamos el icono en formato inline SVG (etiqueta <svg> en lugar de <img>)
Errores comunes al usar iconos SVG personalizados en ACF y cómo solucionarlos
Trabajar con iconos SVG personalizados en ACF suele ser muy estable, pero hay algunos fallos típicos que pueden aparecer durante la implementación. Vamos a repasar los más frecuentes y cómo resolverlos de forma sencilla.
- Organiza tus iconos SVG por nombre claro y semántico. Evita nombres como icon1.svg, usa arrow-left.svg, email-outline.svg, etc.
- Válida que los SVG estén optimizados. Usa herramientas como SVGO para limpiar atributos innecesarios.
- Revisa que la ruta al SVG sea correcta. Si el icono no aparece, comprueba que el filtro de ACF devuelve la URL real de la carpeta.
- Cuidado con el tema hijo. Si los iconos están ahí, usa get_stylesheet_directory_uri() en lugar de get_template_directory_uri() para evitar 404.
- Atento a la caché. Si cambias un icono y no se actualiza, renombra el archivo (icon-bolt-v2.svg) o añade una query string (bolt.svg?v=2).
Con estas precauciones, evitarás la mayoría de los problemas al trabajar con WordPress custom icons en ACF y tu selector visual será estable y fácil de mantener.
Buenas prácticas y consejos adicionales
Además de evitar errores, hay varias formas de sacar más partido a tu biblioteca de iconos SVG con ACF. Aquí tienes algunos consejos que aplicamos en proyectos reales:
- Usa nombres coherentes y consistentes. Define un patrón (ej. categoria-accion.svg) y mantenlo en todo el Design System. Esto facilita la búsqueda y el mantenimiento.
- Centraliza tu librería de iconos. Guarda todos los SVG en una única carpeta dentro del tema o plugin, así es más fácil sincronizarla entre entornos.
- Evita depender de librerías externas. Siempre que sea posible, usa iconos propios. Tendrás más control, evitarás dependencias y mejorarás el rendimiento.
- Piensa en escalabilidad. Si tu proyecto va a crecer, prepara la función de carga automática de iconos con glob() para no tener que actualizar manualmente el listado.
- Utiliza campos de tipo bloque ACF para máxima reutilización. Puedes hacer que tus componentes con iconos se dupliquen en múltiples páginas sin rehacer nada.
- Optimiza siempre antes de producción. Un SVG limpio, sin metadatos ni estilos inline, es más ligero y más fácil de controlar con CSS.
En Bubuku aplicamos estas prácticas en proyectos donde el Design System es clave, y la diferencia se nota en la mantenibilidad y en la experiencia del equipo al trabajar con WordPress.
Cómo gestionar iconos personalizados en WordPress con ACF de forma profesional
A lo largo de este artículo hemos visto cómo crear una carpeta de SVG en tu Design System, conectarla con el Icon Picker de ACF, añadir los iconos de forma automática, y finalmente mostrarlos en plantillas y bloques de WordPress.
El resultado es un flujo claro, escalable y alineado con tu proyecto:
- Tus iconos están centralizados y bien organizados.
- El equipo puede elegirlos desde el backend sin memorizar nombres de archivo.
- El frontend muestra exactamente lo que se define en tu Design System o sistema de diseño, garantizando consistencia visual.
Esta integración convierte a ACF en una herramienta clave para llevar un sistema de iconografía profesional a WordPress sin depender de librerías externas.
En Bubuku trabajamos cada día con Design Systems e integraciones en WordPress. Si necesitas ayuda para implementar tu propio sistema de iconos o mejorar la arquitectura de tu web, te invitamos a conocer nuestro servicio de desarrollo web WordPress a medida.
He tomado como referencia la documentación oficial de ACF sobre el campo Icon Picker (en inglés). Ese artículo no entra tanto en profundidad como implementarlo en proyectos reales, pero me sirvió como punto de partida para comprobar personalmente su potencial.
