Cómo registrar iconos SVG personalizados en WordPress 7.1
WordPress 7.1 incorpora una API pública para registrar iconos SVG personalizados sin JavaScript ni proceso de compilación. Desde un plugin podrás agruparlos en colecciones, elegirlos desde el bloque core/icon, renderizarlos en PHP y consultarlos a través de la API REST.
La versión 7.1 está prevista para el 19 de agosto de 2026. Esta guía crea un plugin pequeño con tres iconos, automatiza el registro de una carpeta completa y muestra cómo reutilizar los iconos en el editor, en plantillas PHP y como iconos de bloques.
Requisitos
Necesitas WordPress 7.1 o posterior; la versión candidata 7.1 RC sirve para desarrollar. Prepara también algunos archivos SVG, un entorno local como LocalWP, WordPress Studio o wp-env, y conocimientos básicos de PHP.
Qué aporta la API de iconos
La API gira en torno a tres funciones y a las colecciones. Una colección es un grupo con nombre que actúa como espacio de nombres: evita que myplugin/plus entre en conflicto con core/plus o con el icono de otro plugin.
wp_register_icon_collection( $name, $args ): crea una colección de iconos con nombre.wp_register_icon( $name, $args ): registra un icono individual.wp_get_icon( $name, $args ): devuelve el SVG de un icono como una cadena para renderizarlo en PHP.
Cada icono debe pertenecer a una colección y su identificador sigue el patrón coleccion/slug-del-icono. Al registrarlo, aporta el SVG mediante content, con el marcado SVG como cadena dentro de PHP, o mediante file_path, con la ruta absoluta de un archivo .svg. Elige solo una de las dos opciones para cada icono: content resulta cómodo para uno o dos SVG; file_path encaja mejor con bibliotecas almacenadas en una carpeta.
1. Crea el plugin y registra la colección
Registra la colección antes que cualquiera de sus iconos. Si intentas añadir un icono a una colección que aún no existe, no aparecerá en el selector sin mostrar un error.
Crea esta estructura dentro de wp-content/plugins/:
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgAñade la cabecera del plugin y conecta el registro de la colección al hook init. La prioridad predeterminada es 10.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Registra iconos SVG personalizados para WordPress 7.1+.
* Version: 1.0.0
* Requires at least: 7.1
* Requires PHP: 7.4
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
define( 'MYPLUGIN_ICONS_PATH', plugin_dir_path( __FILE__ ) );
/**
* Registra primero la colección de iconos.
*/
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}El nombre myplugin será el prefijo de myplugin/heart, myplugin/star y los demás iconos. label se muestra como encabezado de sección en el selector. Activa el plugin desde Plugins > Plugins instalados; una colección vacía no renderiza nada todavía.
2. Registra iconos en línea y desde archivos
Puedes mezclar ambos métodos en la misma colección. Registra el corazón en línea y carga la estrella y el marcador desde archivos para comparar los dos flujos.
Registra un SVG con content
Inserta el SVG del corazón directamente en el archivo PHP. Este método evita crear archivos adicionales cuando la colección solo necesita uno o dos iconos.
/**
* Registra un icono mediante contenido SVG en línea.
*/
add_action( 'init', 'myplugin_register_inline_icons', 20 );
function myplugin_register_inline_icons() {
wp_register_icon(
'myplugin/heart',
array(
'label' => __( 'Heart', 'myplugin-icons' ),
'content' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z"/></svg>',
)
);
}- El hook usa prioridad
20, posterior a la prioridad10con que se registra la colección. - El nombre
myplugin/heartune el nombre de colección y el slug del icono. labelidentifica el icono en el selector ycontentcontiene su marcado SVG.stroke="currentColor"hace que el icono herede el color del texto, sin fijar un color.
Registra SVG desde archivos
Guarda estos dos SVG en la carpeta icons/. Para una biblioteca que crece, mantener los iconos como archivos independientes simplifica el mantenimiento.
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/>
</svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"/>
</svg>/**
* Registra iconos desde archivos .svg.
*/
add_action( 'init', 'myplugin_register_file_icons', 20 );
function myplugin_register_file_icons() {
wp_register_icon(
'myplugin/star',
array(
'label' => __( 'Star', 'myplugin-icons' ),
'file_path' => MYPLUGIN_ICONS_PATH . 'icons/star.svg',
)
);
wp_register_icon(
'myplugin/bookmark',
array(
'label' => __( 'Bookmark', 'myplugin-icons' ),
'file_path' => MYPLUGIN_ICONS_PATH . 'icons/bookmark.svg',
)
);
}Aquí solo cambia content por file_path; WordPress lee el archivo cuando lo necesita. Abre el bloque core/icon en el editor: aparecerá la sección MyPlugin con Heart, Star y Bookmark.
El fallo más habitual
Si un icono no aparece, revisa el orden de registro. Registra la colección con la prioridad predeterminada y los iconos con una prioridad posterior, como 20.
3. Registra todos los SVG de una carpeta
Llamar a wp_register_icon() una vez por cada icono deja de ser práctico cuando la biblioteca crece. Sustituye la función de registro individual desde archivos por este patrón masivo: detecta cada SVG de la carpeta y lo registra en cada petición.
add_action( 'init', 'myplugin_register_all_file_icons', 20 );
function myplugin_register_all_file_icons() {
$icons_dir = MYPLUGIN_ICONS_PATH . 'icons/';
$svg_files = glob( $icons_dir . '*.svg' );
if ( empty( $svg_files ) ) {
return;
}
foreach ( $svg_files as $file_path ) {
$slug = basename( $file_path, '.svg' );
$label = ucwords( str_replace( '-', ' ', $slug ) );
wp_register_icon(
'myplugin/' . $slug,
array(
'label' => $label,
'file_path' => $file_path,
)
);
}
}glob( $icons_dir . '*.svg' )devuelve todos los archivos.svgde la carpeta.basename( $file_path, '.svg' )elimina la ruta y la extensión:advanced-button.svgpasa a seradvanced-button.ucwords( str_replace( '-', ' ', $slug ) )genera una etiqueta legible:advanced-buttonse convierte en «Advanced Button».- El bucle añade cada icono a la colección
myplugin/.
Añade un SVG nuevo a icons/, recarga el editor y estará disponible en el selector sin cambiar el código. El patrón permite conservar el corazón registrado en línea y cargar desde la carpeta la estrella, el marcador y cualquier icono adicional.
4. Usa los iconos en el editor, PHP y bloques
Insértalos con el bloque core/icon y consúltalos por REST
El selector del bloque core/icon muestra automáticamente todas las colecciones registradas y el icono se renderiza en el frontend tras insertarlo. También quedan disponibles para herramientas externas que consuman datos de WordPress en /wp-json/wp/v2/icons; las colecciones se exponen en /wp-json/wp/v2/icon-collections.
Renderízalos en plantillas PHP
wp_get_icon() devuelve el SVG como una cadena, así que puedes imprimirlo directamente o envolverlo con tu propio HTML.
echo wp_get_icon( 'myplugin/heart' );Pasa un segundo array para definir dimensiones, una clase CSS y una etiqueta accesible.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);sizeestablece elwidthy elheightdel SVG en píxeles.classañade una clase CSS al elemento SVG.labelestablecearia-labelpara los lectores de pantalla.
Añade un shortcode para el contenido
Este shortcode permite insertar cualquier icono registrado junto a un texto en entradas, páginas y widgets. Sanitiza el nombre, el tamaño y la clase antes de generar el marcado.
add_shortcode( 'myplugin_icon', 'myplugin_icon_shortcode' );
function myplugin_icon_shortcode( $atts ) {
$atts = shortcode_atts(
array(
'name' => 'heart',
'text' => '',
'size' => 24,
'class' => '',
),
$atts
);
$icon = wp_get_icon(
'myplugin/' . sanitize_key( $atts['name'] ),
array(
'size' => absint( $atts['size'] ),
'class' => sanitize_html_class( $atts['class'] ),
)
);
if ( ! $icon ) {
return '';
}
return sprintf(
'<span>%s %s</span>',
$icon,
esc_html( $atts['text'] )
);
}[myplugin_icon name="heart" text="Hello World"]
[myplugin_icon name="star" text="Featured post" size="32"]
[myplugin_icon name="bookmark" text="Save for later" size="20"]El atributo size fija el tamaño y currentColor hace que el SVG adopte de forma automática el color del texto que lo rodea.
Úsalos como iconos de bloques
Un icono registrado puede sustituir al Dashicon predeterminado al registrar cualquier bloque. Funciona tanto con bloques registrados mediante JavaScript como con bloques registrados solo desde PHP.
'icon' => 'warning', // Usa un Dashicon.'icon' => 'myplugin/star', // Usa un SVG personalizado registrado.El insertador de bloques mostrará el SVG personalizado en vez del Dashicon genérico. Un único registro alimenta el editor, las plantillas PHP y la API REST.
5. Diseña SVG que se adapten al sitio
Un icono integrado debe heredar el color del contexto, escalar con la tipografía y responder a estados como hover. El patrón clave consiste en usar stroke="currentColor" o fill="currentColor" en lugar de colores fijos.
<!-- Evita fijar un color: este icono siempre será rojo. -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>Con currentColor, un icono dentro de texto rojo será rojo; en un tema oscuro adoptará el color oscuro y dentro de un enlace coincidirá con el enlace. Así el SVG se comporta como texto y no desentona con el tema.
Cuando un icono necesita un color concreto, como una marca o un indicador de estado, aplica color con CSS a la clase que pasaste a wp_get_icon().
.featured-icon {
color: #f59e0b; /* Ámbar, sin depender del texto circundante. */
}Como el SVG usa currentColor, el valor de color se propaga al stroke o al fill, incluso si el texto cercano usa otro color.
Para los iconos renderizados con el shortcode o con wp_get_icon(), size resuelve el tamaño en píxeles. Si necesitas controlar el tamaño con CSS o añadir una interacción al pasar el cursor, aplica estilos al contenedor.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Usa
sizeenwp_get_icon()para un caso aislado donde importe un tamaño exacto en píxeles y no merezca escribir CSS. - Usa clases CSS, mediante el argumento
classo en el elemento contenedor, si el icono se repite y debe mantener un estilo común, o si depende de un estado comohover,focusoactive, o de un contexto como un enlace o un encabezado. - En el shortcode, ajusta casos concretos con el atributo
sizey aplica consistencia global con CSS sobre.myplugin-icon-inline svg.
6. Elimina iconos y colecciones
WordPress 7.1 incluye una función para anular el registro de un icono y otra para eliminar una colección entera.
Elimina un icono
Durante el desarrollo o al retirar un icono en una actualización, elimínalo con wp_unregister_icon().
wp_unregister_icon( 'myplugin/bookmark' );El icono desaparecerá del selector en la siguiente petición. Si una entrada ya contiene ese icono dentro de un bloque core/icon, el bloque quedará vacío: WordPress no reescribe el contenido de las entradas.
Limpia la colección al desactivar el plugin
Al desactivar el plugin, elimina su colección para retirar todos sus iconos del selector de una vez. No necesitas recorrer cada icono.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Preguntas frecuentes
¿Debo registrar la colección antes que los iconos?
Sí. Los iconos deben pertenecer a una colección existente o no aparecerán en el selector. Registra la colección en init con la prioridad predeterminada y registra los iconos después, por ejemplo con prioridad 20.
¿Puedo mezclar iconos con content y con file_path en una colección?
Sí. Cada llamada a wp_register_icon() es independiente. Usa content para uno o dos iconos y file_path para el resto; WordPress los trata igual una vez registrados.
¿Funcionan como iconos de bloque en register_block_type()?
Sí. Pasa el nombre completo del icono registrado, como 'myplugin/star', a la clave icon de register_block_type(). El insertador mostrará el SVG personalizado en lugar de un Dashicon, tanto en bloques con JavaScript como en bloques solo con PHP.
¿wp_get_icon() devuelve HTML o una cadena?
Devuelve el SVG como una cadena. Puedes imprimirla directamente o envolverla en tu propio HTML. El segundo array $args acepta size, class, label para aria-label y title.
¿Qué atributos SVG debo eliminar antes de registrar un icono?
Elimina los colores fijos de fill y stroke, y también los atributos width y height del elemento raíz <svg>; conserva viewBox. Quita además los bloques <style>, los scripts y todo lo que no resulte necesario. Mantén viewBox y los atributos estructurales, y usa currentColor en las referencias de color.
¿Puedo registrar iconos desde un tema en vez de un plugin?
Sí. La misma llamada a wp_register_icon() funciona desde el archivo functions.php de un tema si usas get_stylesheet_directory() para construir la ruta del archivo. Ten presente que los iconos registrados por el tema desaparecen cuando cambias de tema.
¿Qué ocurre si dos colecciones usan el mismo nombre de icono?
Las colecciones actúan como espacio de nombres, por lo que myplugin/heart y otherplugin/heart pueden coexistir sin conflicto. El nombre completo, incluido el prefijo de la colección, es lo que identifica de forma única cada icono.
¿WordPress sanitiza los SVG al registrarlos?
No. WordPress no modifica el contenido SVG durante el registro: sirve exactamente la cadena proporcionada o el contenido del archivo indicado. Sanitiza los SVG antes de distribuirlos y elimina scripts, referencias externas y cualquier elemento innecesario.
Prepara tu biblioteca de iconos
Empieza por registrar una colección en init, añade los iconos después y usa content o file_path según el tamaño de la biblioteca. Si mantienes muchos SVG, adopta el patrón con glob() para que cada archivo nuevo se incorpore sin añadir llamadas manuales.
Diseña los SVG con currentColor, elimina contenido activo antes de distribuirlos y conserva los nombres completos de colección al usarlos en bloques, plantillas y shortcodes. Así podrás ofrecer una experiencia de editor propia sin proceso de compilación de JavaScript.
María García
Editora del equipo español, especialista en e-commerce y WooCommerce. Construir y optimizar tiendas online es mi perfil principal. Disfruto de las soluciones creativas.
Todas las publicaciones
