👉 Cómo solucionar '$ is not a function' en WordPress: 4 formas
Usted edita functions.php, añade un par de líneas de jQuery y el sitio falla con una pantalla en blanco. La consola muestra: Uncaught TypeError: $ is not a function. ¿Le suena familiar?
Todo desarrollador de WordPress se encuentra con este error al menos una vez. Copia código jQuery que funciona desde CodePen o un fragmento, lo pega en su sitio y WordPress no lo entiende. La razón no es un código roto ni conflictos de plugins. La razón es cómo WordPress maneja jQuery.
Cubriremos cuatro métodos probados para solucionar el error «$ is not a function», desde el envoltorio seguro IIFE hasta desactivar completamente noConflict. Cada método incluye código listo para copiar y pegar.
💡 Resumen rápido:
- Envuelva el código jQuery en una función anónima IIFE, el método más seguro y universal
- Use jQuery document ready con un parámetro dólar para scripts en el head
- Asigne su propio alias mediante noConflict, práctico cuando el signo dólar está ocupado por otra librería
- Desactive noConflict globalmente, solo cuando no haya otras librerías en el sitio
Por qué ocurre el error «$ is not a function» en WordPress
WordPress carga jQuery en modo noConflict. Esto significa que la variable $, el alias corto de jQuery, no está disponible globalmente. Los desarrolladores del núcleo de WordPress lo hicieron intencionadamente para evitar conflictos: muchas librerías JavaScript (Prototype, MooTools, versiones antiguas de Bootstrap) también usan $ como su atajo principal.
Cuando usted escribe en su script:
1 $("#element").hide();
WordPress no sabe que $ es jQuery. Ve una llamada a una función desconocida y lanza TypeError: $ is not a function. Fuera de WordPress, en una página HTML «desnuda», este mismo código funcionaría sin problemas, ya que jQuery registra $ globalmente allí.
Técnicamente, WordPress solo entiende el nombre completo: jQuery("#element").hide(). Pero escribir jQuery en lugar de $ en cada línea de un script extenso es incómodo, el código se hincha y pierde legibilidad. Afortunadamente, hay cuatro maneras de sortear esta limitación.
Antes de editar cualquier archivo del tema, haga una copia de seguridad de su sitio. Un punto y coma omitido en functions.php y el sitio se cae. Con una copia de seguridad, puede revertir los cambios en un minuto.
Método 1: envoltorio IIFE, seguro y universal
La forma más fiable de recuperar $ en scripts de WordPress es una expresión de función invocada inmediatamente (IIFE, por sus siglas en inglés). Pasa jQuery como argumento y dentro de la función se refiere a él mediante el familiar $.
Código para footer.php o inserción de bajo nivel (pie del sitio):
1 (function($) { 2 // Your jQuery code here 3 $("#element").hide(); 4 })(jQuery);
Lo que sucede aquí: una función anónima acepta el parámetro $ y se invoca inmediatamente con el argumento jQuery. Dentro de esta función $ === jQuery, mientras que fuera $ permanece indefinido. El conflicto con otras librerías queda eliminado.
Este método funciona para scripts en el footer. Si el script debe ejecutarse en el <head>, use el método 2.
Método 2: jQuery(document).ready con parámetro $
Cuando un script debe ejecutarse en el encabezado de la página (antes de que cargue el DOM), envuélvalo en jQuery(document).ready. Nota: el $ se pasa al parámetro del callback, esto no es un error tipográfico sino un punto clave.
Código para header.php o functions.php mediante wp_enqueue_script:
1 jQuery(document).ready(function($) { 2 // Your jQuery code here 3 console.log($); 4 });
El método .ready() espera la carga completa del DOM, y jQuery se pasa a sí mismo al callback como $. Dentro de este callback, $ funciona de nuevo como en un entorno JavaScript normal. Y, a diferencia del método 1, el script arranca desde el <head>, lo cual es útil para operaciones críticas de inicialización.
La mayoría de los desarrolladores de temas y plugins conocen esta peculiaridad de WordPress, por lo que en productos de calidad casi siempre verá jQuery en lugar de $, o uno de los envoltorios anteriores.
Método 3: cree su propio alias mediante noConflict
jQuery le permite no solo recuperar $, sino también asignar cualquier otro alias corto, por ejemplo las variables $j o jq, o cualquier variable que prefiera. Esto es conveniente cuando el sitio ya usa otra librería que ha tomado $.
1 var jq = jQuery.noConflict(); 2 jq("div p").hide(); 3 4 // Another library continues using its own $ 5 $("content").style.display = "none";
El método jQuery.noConflict() libera $ para otras librerías y devuelve jQuery a su variable (jq en el ejemplo). Después de esto, las llamadas se hacen mediante jq(...), mientras que $ funciona para la librería vecina, el conflicto desaparece por completo.
Este enfoque es especialmente útil en sitios donde un tema de WordPress convive con un framework JavaScript de terceros que usa $ para sus propios fines.
Método 4: desactive completamente noConflict (usar con precaución)
Si sabe con certeza que el sitio no tiene otras librerías que reclamen $, puede desactivar el modo noConflict globalmente:
1 $ = jQuery.noConflict(true);
Después de esta línea, $ vuelve a funcionar como alias global de jQuery en todas partes, en cualquier script, en cualquier lugar de la página. Sin embargo, este método es el más arriesgado. Si más tarde instala un plugin que también usa $, el sitio se romperá con un error difícil de reproducir.
Recomendamos los métodos 1 y 2 como principales, son seguros, aislados y cubren la gran mayoría de los escenarios reales. El método 4 es para situaciones en las que mantiene un script heredado grande y no puede envolver cada función por separado.
En el video anterior, una demostración visual de los cuatro métodos en acción. Véalo si prefiere la explicación visual al texto.
⁉️🤔 Preguntas frecuentes
¿Por qué WordPress desactivó $ para jQuery en primer lugar?
Los desarrolladores del núcleo de WordPress activaron
jQuery.noConflict()por defecto para proteger los sitios de conflictos con otras librerías JavaScript. Prototype.js, MooTools y algunos frameworks antiguos también registran una variable global$. Si WordPress le diera$a jQuery, cualquier tema o plugin con una librería así rompería el panel de administración o el frontend. WordPress ejecuta jQuery en modo noConflict desde la versión 3.6, esto no es un error sino una decisión arquitectónica. La variable$en el ámbito global permanece libre para librerías de terceros. Es exactamente por eso que$("#id")fuera de un envoltorio siempre lanzaráTypeError.
¿Puedo simplemente incluir jQuery una segunda vez, fuera de WordPress?
Técnicamente, sí, puede incluir jQuery mediante un enlace CDN una segunda vez, y registrará
$globalmente. Pero esta es una mala práctica: dos versiones de jQuery en una página entran en conflicto, el tamaño de la página aumenta y los plugins de WordPress esperan exactamente la versión de jQuery registrada mediantewp_enqueue_script. Trabaje siempre con la versión de jQuery que proporciona WordPress, está probada para compatibilidad con el núcleo y el panel de administración. Incluir jQuery de nuevo significa crear nuevos problemas en lugar de resolver el original.
¿Qué hacer si el error aparece solo en páginas específicas?
Compruebe si la página específica carga un script de terceros mediante un plugin o widget. Algunos plugins de caché y minificación reordenan los scripts de forma agresiva, y jQuery puede cargarse después de su código. Desactive los plugins de optimización uno por uno para encontrar al culpable. En la mayoría de los casos, el problema de «$ is not a function en una sola página» se debe al orden de carga de los scripts. Un plugin de minificación o caché coloca su script antes que jQuery, y
$aún no existe en el momento de la llamada. Solución: excluya el script de la minificación o envuélvalo en el IIFE del método 1, que no depende de$global.
¿Existe un plugin ya hecho que solucione este error?
No hay un plugin dedicado «para arreglar $ is not a function», y no es necesario. El problema se resuelve con un envoltorio de una línea, e instalar un plugin aparte para esto es excesivo. Sin embargo, hay plugins como Code Snippets que le permiten añadir código JavaScript y PHP sin editar archivos del tema, lo cual es más seguro para principiantes. Code Snippets almacena su código en la base de datos, no en
functions.php. Si comete un error de sintaxis, el plugin revierte automáticamente los cambios y el sitio no se cae. Recomendamos a los principiantes añadir cualquier código JS a través de él, no editando archivos del tema.
El error «$ is not a function» está solucionado, ¿y ahora qué?
Conclusión principal: el problema no está en su código ni en WordPress. Este es un comportamiento estándar del CMS, y se soluciona con un envoltorio. En la gran mayoría de los casos, el método 1 (IIFE) o el método 2 (.ready() con $) es suficiente. No rompen otros scripts y funcionan en cualquier versión de WordPress, desde la 4.0 hasta la más reciente.
Si trabaja a menudo con jQuery en WordPress, adquiera el hábito de comenzar cada script con (function($) { y terminar con })(jQuery);, esto se convertirá en memoria muscular en una semana y eliminará el error para siempre.
Comparta el artículo con colegas que aún editan functions.php a base de prueba y error, un envoltorio listo para usar les ahorrará una hora de depuración.
Un equipo profesional de escritores y editores especializados en la creación de contenido de calidad.