Skip to content

jQuery Hoja de referencia

Librería de JavaScript rápida, pequeña y rica en funcionalidades.

01

Primeros pasos

Incluir jQuery

Incluye jQuery vía un CDN para una carga rápida y cacheada. La versión minificada (.min.js) es para producción; la sin comprimir es para depurar. Proporciona siempre un respaldo local por si el CDN no está accesible. Con npm puedes importar jQuery como módulo — útil para bundlers como Webpack/Vite. jQuery 3.7.x es la línea actual; los IE antiguos ya no están soportados.

jquery
<!-- Production (CDN, minified) -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>

<!-- Development (CDN, uncompressed) -->
<script src="https://code.jquery.com/jquery-3.7.1.js"></script>

<!-- Fallback: load local if CDN fails -->
<script>
window.jQuery || document.write(
  '<script src="js/jquery-3.7.1.min.js"><\/script>'
)
</script>

<!-- npm install -->
<!-- npm install jquery -->

Documento listo

Envuelve el código que manipula el DOM en $(document).ready() para que corra solo después de parsearse el árbol del DOM (sin esperar imágenes). $(fn) es la forma corta. Si tu <script> está al final de <body>, el DOM ya está disponible y puedes saltarte ready. El ready de jQuery es similar a DOMContentLoaded — se dispara antes de window.load (que espera imágenes/iframes).

jquery
// run code after DOM is fully parsed
$(document).ready(function () {
  console.log('DOM ready')
})

// shorter equivalent
$(function () {
  console.log('DOM ready')
})

// modern preferred (no ready needed at end of body)
// <script> at the end of <body> runs after DOM exists

// pass a function to $ — jQuery treats it as ready handler
$(function () {
  $('.btn').on('click', function () {
    alert('clicked')
  })
})

El objeto jQuery ($)

$ es solo un alias de jQuery — ambos funcionan igual. Como función, $ selecciona elementos (devuelve una colección jQuery). Como espacio de nombres, $.foo ofrece funciones utilitarias. Si otra librería usa $, llama a $.noConflict() para liberarlo; puedes seguir usando jQuery o pasar $ a un callback de ready para aliarlo localmente.

jquery
// $ is an alias for jQuery
console.log($ === jQuery)  // true

// $ as a function: select elements
$('p')             // all paragraphs
$('#main')         // element with id main
$('.btn.primary')  // elements with class btn and primary

// $ as a namespace: utility methods
$.each([1, 2, 3], function (i, v) { console.log(i, v) })
$.extend({}, defaults, options)
$.type([])         // 'array'

// noConflict: release $ back to other libraries
$.noConflict()
jQuery(function ($) { /* $ available here */ })

Encadenar funciones

La mayoría de funciones de jQuery devuelven la misma colección jQuery, así que puedes encadenar llamadas — la característica distintiva de jQuery. Usa .end() para volver al conjunto anterior tras una función de recorrido (.find(), .filter()). La indentación hace legibles los recorridos encadenados. Evita cadenas demasiado largas — se vuelven difíciles de depurar. Para funciones no encadenables (como el getter de .width()), la cadena se rompe porque devuelven un valor, no la colección.

jquery
// most methods return the jQuery object, enabling chains
$('.box')
  .addClass('active')
  .css('color', 'red')
  .slideDown(300)
  .text('Hello')

// break across lines for readability
$('#nav')
  .find('.item')
    .addClass('highlight')
    .end()
  .find('.link')
    .attr('target', '_blank')

// .end() pops the current filter back to previous set

Modo sin conflictos

$.noConflict() devuelve el control de $ a la librería que lo definió primero. Tras llamarlo, usa el nombre completo jQuery, o asigna jQuery a una variable personalizada. El patrón IIFE (function($){...})(jQuery) es la forma clásica de mantener $ como alias local dentro de tu módulo mientras dejas el $ global para otras librerías — esencial en WordPress y entornos heredados.

jquery
// release $ to other libraries (e.g., Prototype)
$.noConflict()

// use jQuery full name
jQuery('.btn').on('click', function () { /* ... */ })

// or assign jQuery to a custom alias
const jq = $.noConflict()
jq('.btn').hide()

// IIFE pattern: keep $ inside a local scope
(function ($) {
  $('.btn').on('click', function () { /* ... */ })
})(jQuery)
02

Selectores

Selectores básicos

jQuery usa selectores CSS (mayormente compatibles con querySelectorAll). Los tres grandes: nombre de etiqueta, #id, .clase. La coma combina selectores (unión). #id es el más rápido (usa getElementById). El universal * es lento — evítalo en documentos grandes. Los resultados de los selectores son siempre una colección jQuery (tipo array), incluso si coinciden 0 o 1 elementos.

jquery
// element selector
$('div')          // all <div> elements
$('p')            // all <p> elements

// id selector
$('#header')      // element with id="header"

// class selector
$('.btn')         // all elements with class="btn"
$('.btn.primary') // .btn AND .primary

// multiple (comma = OR)
$('div, p, .btn') // divs, paragraphs, and .btn

// universal
$('*')            // all elements (slow — avoid)

Jerarquía y combinadores

Los combinadores describen relaciones: espacio (descendiente), > (hijo directo), + (hermano adyacente), ~ (hermano general). La evaluación de derecha a izquierda significa que $('ul li') encuentra primero los <li> y luego filtra los que están dentro de <ul> — así que los selectores concretos del lado derecho rinden mejor. Evita combinadores profundos en documentos enormes; acota a un contenedor vía $(contenedor).find(...) para mejor rendimiento.

jquery
// descendant: space (any depth)
$('ul li')        // <li> anywhere inside <ul>

// child: > (direct children only)
$('ul > li')      // <li> directly inside <ul>

// adjacent sibling: + (immediately next)
$('h2 + p')       // <p> right after <h2>

// general sibling: ~ (all following siblings)
$('h2 ~ p')       // all <p> siblings after <h2>

// multiple levels
$('#nav .item > a span')

Selectores de atributo

Los selectores de atributo apuntan a elementos por valores de atributo: [attr] (presencia), [attr=val] (exacto), [attr^=val] (empieza), [attr$=val] (termina), [attr*=val] (contiene), [attr~=val] (palabra). Entrecomilla los valores por seguridad. [attr!=val] es una extensión exclusiva de jQuery (usa .not('[attr=val]') por compatibilidad con CSS). Útil para formularios (tipos de input), enlaces (patrones href) y atributos data-*.

jquery
// has attribute
$('[href]')                 // any element with href
$('[data-id]')              // any element with data-id

// exact value
$('[type="text"]')          // type="text"
$('[href="https://example.com"]')

// substring matches
$('[href^="https"]')        // starts with "https"
$('[href$=".pdf"]')         // ends with ".pdf"
$('[href*="example"]')      // contains "example"

// whitespace-separated word
$('[class~="active"]')      // class contains word "active"

// inequality (jQuery extension, not CSS)
$('[href!="https://x.com"]')

Selectores de formularios e inputs

Los pseudo-selectores de formulario (:input, :text, :checked, etc.) son extensiones de jQuery — no forman parte de CSS, así que no pueden usar el camino rápido de querySelectorAll. Por rendimiento en formularios grandes, usa $('input[type=text]') en lugar de $(':text'). :checked y :selected son esenciales para leer el estado del formulario. Son dinámicos — se reevalúan en cada acceso.

jquery
// :input matches all form controls
$(':input')         // input, textarea, select, button

// by type
$(':text')          // <input type="text">
$(':password')
$(':checkbox')
$(':radio')
$(':submit')
$(':file')

// by state
$(':checked')       // checked checkbox/radio or selected option
$(':selected')      // selected <option>
$(':disabled')
$(':enabled')
$(':focus')

// combined with class
$('input.required:visible')

Selectores de filtro y contenido

Los filtros acotan una selección: :first/:last, :even/:odd (indexados desde 0), :eq(n), :gt(n), :lt(n). Los filtros de contenido (:contains, :has, :empty, :parent) coinciden según el contenido. :visible y :hidden se basan en offsetWidth/Height y CSS (ojo: los elementos con visibility:hidden son :hidden en jQuery 3+; antes eran :visible). Muchos son extensiones de jQuery — prefiere .filter(), .first() y .eq() por mejor rendimiento.

jquery
// basic filters
$('li:first')         // first <li>
$('li:last')          // last <li>
$('li:even')          // even-indexed (0, 2, 4...)
$('li:odd')           // odd-indexed
$('li:eq(2)')         // 3rd <li> (0-indexed)
$('li:gt(2)')         // <li> after index 2
$('li:lt(2)')         // <li> before index 2

// content filters
$('div:contains("Hello")')  // divs containing text "Hello"
$('div:empty')              // divs with no children
$('div:has(p)')             // divs containing <p>
$('div:parent')             // divs that have children

// visibility
$(':visible')
$(':hidden')
03

Eventos

Enlazar eventos con .on()

.on() es el enlazador de eventos moderno unificado (reemplaza a .bind/.delegate/.live). Pasa nombre(s) de evento y un manejador. 'this' dentro del manejador es el elemento del DOM (no envuelto en jQuery — envuélvelo con $(this) si hace falta). Usa espacios de nombres de eventos (click.myapp) para desvincular manejadores concretos sin afectar a otros. Varios eventos pueden compartir un manejador (separados por espacios) o tener manejadores separados (forma de objeto).

jquery
// basic binding
$('.btn').on('click', function (e) {
  console.log('clicked!', this)  // 'this' is the DOM element
})

// multiple events, same handler
$('.box').on('mouseenter mouseleave', function () {
  $(this).toggleClass('hover')
})

// multiple events, different handlers
$('.input').on({
  focus: function () { $(this).addClass('focused') },
  blur: function () { $(this).removeClass('focused') }
})

// named events (for targeted unbinding)
$('.btn').on('click.myapp', handler)
$('.btn').off('click.myapp')  // only removes this one

Delegación de eventos

La delegación de eventos enlaza un manejador a un padre que captura los eventos de los hijos mediante el burbujeo. El segundo selector de .on() ('li') filtra qué hijos disparan el manejador. Ventajas: un manejador en lugar de N, soporte automático para elementos añadidos dinámicamente, menos memoria. Esencial para listas largas o SPAs. 'this' es el hijo coincidente (el li), no el padre. Usa e.delegateTarget para acceder al padre.

jquery
// delegate: handle events on children, now or future
$('#list').on('click', 'li', function (e) {
  // 'this' is the <li> that was clicked
  $(this).toggleClass('done')
})

// works for <li> added AFTER binding too
$('#list').append('<li>New item (also clickable)</li>')

// WHY: instead of binding to each <li>,
// bind ONCE to the parent; clicks bubble up
// - 1 handler instead of N
// - works for dynamically added elements
// - lower memory, faster setup

Objeto de evento y funciones

El objeto de evento (e) lleva información y funciones de control. preventDefault detiene el comportamiento por defecto del navegador (navegación de enlaces, envío de formularios). stopPropagation detiene el burbujeo; stopImmediatePropagation también detiene los demás manejadores del mismo elemento. e.target es el elemento realmente clicado (puede ser un hijo); e.currentTarget es el elemento con el manejador (= this). Pasa datos a los manejadores vía el segundo argumento opcional de .on().

jquery
$('.link').on('click', function (e) {
  e.preventDefault()      // stop default action (e.g., navigation)
  e.stopPropagation()     // stop bubbling to parents
  e.stopImmediatePropagation() // stop other handlers on same element

  console.log(e.type)         // 'click'
  console.log(e.target)       // the actual clicked element
  console.log(e.currentTarget) // the element with the handler (= this)
  console.log(e.which)        // mouse button or key code
  console.log(e.pageX, e.pageY) // mouse coordinates

  // data passed via .on(name, data, handler)
})

$('.btn').on('click', { greeting: 'hi' }, function (e) {
  console.log(e.data.greeting)  // 'hi'
})

Funciones de evento abreviadas

Las funciones abreviadas (.click, .focus, .submit, etc.) enlazan un manejador cuando se llaman con una función, o disparan el evento cuando se llaman sin ella. .hover(enter, leave) es una comodidad para mouseenter+mouseleave. Son equivalentes a .on('evento', fn) pero más cortos. Algunos abreviados (.load, .error) se eliminaron en jQuery 3 — usa .on('load', ...) en su lugar. Prefiere .on() para código nuevo; es más explícito y soporta delegación.

jquery
// shorthand: bind a handler (or trigger if no handler)
$('.btn').click(function () { /* ... */ })
$('.btn').click()  // trigger click

// common shorthands
$('.box').hover(enterFn, leaveFn)   // mouseenter + mouseleave
$('.input').focus(function () { /* ... */ })
$('.input').blur(function () { /* ... */ })
$('.form').submit(function (e) {
  e.preventDefault()
  /* ... */
})
$('.el').mouseenter(fn).mouseleave(fn).mousemove(fn)
$(window).resize(fn).scroll(fn)

// deprecated: .load(), .unload(), .error() (removed in jQuery 3)

Disparar y eventos de un solo uso

.trigger('evento') dispara los manejadores Y el comportamiento nativo (por ejemplo, la navegación); .triggerHandler() dispara solo los manejadores enlazados por jQuery y devuelve el valor de retorno del manejador (no encadenable). .one() enlaza un manejador que se autoelimina tras la primera invocación — perfecto para pistas al primer clic o configuraciones únicas. Los eventos personalizados permiten comunicar componentes: $(document).trigger('myapp:ready') y los oyentes se suscriben con .on('myapp:ready', fn).

jquery
// trigger an event programmatically
$('.btn').trigger('click')
$('.btn').click()  // shorthand

// trigger with extra data
$('.box').trigger('custom', [1, 2, 3])

// custom events
$('.box').on('custom', function (e, a, b, c) {
  console.log(a, b, c)  // 1 2 3
})

// fire handler only once
$('.btn').one('click', function () {
  alert('This fires only once')
})

// trigger only native handlers, not custom
$('.link').triggerHandler('click')
04

Manipulación del DOM

Obtener y fijar contenido

.html() trabaja con marcado HTML (como innerHTML) — las etiquetas se parsean. .text() es para texto plano — las etiquetas se escapan y se muestran literalmente (más seguro contra XSS para entrada de usuario). .val() es para controles de formulario (input, select, textarea). Los tres son getters (devuelven el valor del primer elemento) al llamarse sin argumentos, y setters (se aplican a cada elemento coincidente) al llamarse con argumento. Los setters aceptan un callback (índice, valorAntiguo) => valorNuevo.

jquery
// .html(): get or set HTML content
$('#box').html()                    // get innerHTML
$('#box').html('<p>Hello</p>')      // set innerHTML

// .text(): get or set text (HTML-escaped)
$('#box').text()                    // get text content
$('#box').text('<p>Not parsed</p>') // displays literally

// setter with callback (index, old value)
$('p').text(function (i, oldText) {
  return i + ': ' + oldText
})

// .val(): form value
$('input').val()                    // get
$('input').val('new value')         // set
$('select').val()                   // get selected value
$('select').val(['a', 'b'])         // multi-select

Insertar elementos

Crea elementos pasando HTML a $(): $('<div class="x">...</div>'). Append/prepend insertan dentro (al final/principio); before/after insertan fuera (como hermanos). Las variantes 'To' (appendTo, prependTo, insertBefore, insertAfter) invierten el sujeto — útiles para encadenar sobre el elemento nuevo. Los elementos recién insertados heredan manejadores de eventos si se enlazaron vía delegación, pero no si se enlazaron directamente antes de la inserción.

jquery
// create new element
const $li = $('<li class="item">New item</li>')

// add as last child of each matched element
$('ul').append($li)
$('ul').append('<li>Direct string</li>')

// add as first child
$('ul').prepend('<li>First</li>')

// insert before/after matched elements
$('.box').before('<hr>')
$('.box').after('<hr>')

// reverse direction (insert target into container)
$('<p>Hi</p>').appendTo('#main')   // same as $('#main').append(...)
$('<p>Hi</p>').insertBefore('#nav')

Eliminar y reemplazar

.remove() elimina elementos y limpia sus datos/eventos. .detach() los quita del DOM pero conserva datos/eventos — útil para reubicar elementos temporalmente. .empty() borra los hijos pero conserva el elemento. .replaceWith() intercambia cada elemento por contenido nuevo. .unwrap() quita al padre, promoviendo al elemento hacia arriba. Usa siempre .remove() o .detach() — nunca simplemente .html('') sobre un padre, que filtra datos/eventos de los hijos.

jquery
// remove element (and its data + events)
$('.box').remove()

// detach: remove but keep events/data (for re-insertion)
const $el = $('.box').detach()
// ... later
$('body').append($el)  // events still work

// empty: remove all children (keep element)
$('.box').empty()

// replace with new content
$('.old').replaceWith('<div class="new">New</div>')

// unwrap: remove parent (keep element)
$('.box').unwrap()

Envolver y clonar

.wrap() envuelve cada elemento individualmente; .wrapAll() envuelve el conjunto entero como un grupo; .wrapInner() envuelve el contenido (no el elemento en sí). .clone() crea una copia profunda — pasa true para clonar también los manejadores de eventos y los datos (por defecto false, así que los manejadores no se disparan sobre la copia). .unwrap() elimina el padre inmediato. Son potentes para reestructurar marcado sin reescribir cadenas HTML.

jquery
// wrap each element in a structure
$('p').wrap('<div class="wrapper"></div>')
// each <p> becomes <div class="wrapper"><p>...</p></div>

// wrap all matched elements together
$('p').wrapAll('<div class="all"></div>')

// wrap inner contents
$('p').wrapInner('<span></span>')
// <p><span>...</span></p>

// clone (with events)
const $copy = $('.box').clone(true)  // true = clone events too
$('body').append($copy)

// unwrap (remove wrapper)
$('.box').unwrap()

Iterar y filtrar

.each() itera — 'this' es el elemento crudo del DOM; devuelve false para romper, cualquier otra cosa para continuar. .map() transforma a una nueva colección jQuery; llama a .get() para convertir a un array plano. .filter() acota por selector o callback; .not() es el inverso. .is() devuelve un booleano (¿coincide algún elemento?) — útil para condicionales. Evita los bucles for con .eq(i); usa .each() o .map() para un jQuery idiomático.

jquery
// .each: iterate (this = DOM element, i = index)
$('li').each(function (i, el) {
  console.log(i, this, el)  // el === this
  if (i === 2) return false  // break
  // return true to continue
})

// .map: transform to new array
const ids = $('li').map(function (i, el) {
  return $(el).data('id')
}).get()  // .get() converts to plain array

// .filter: keep matching
$('li').filter('.active').addClass('on')
$('li').filter(function (i) { return i % 2 === 0 })

// .not: remove matching
$('li').not('.active').addClass('off')

// .is: returns boolean (does ANY match?)
if ($('li').is('.active')) { /* at least one is active */ }
05

Manipulación de CSS

Obtener y fijar propiedades CSS

.css() obtiene estilos calculados (siempre el valor resuelto, incluso de reglas CSS) o fija estilos en línea. Para getters, pasa un solo nombre de propiedad (devuelve una cadena). Para setters, pasa (prop, valor) o un objeto de pares prop:valor. Los nombres de propiedad pueden ser camelCase o kebab-case (el segundo necesita comillas). Los valores numéricos por defecto van en píxeles para la mayoría de propiedades. Evita .css() para el layout — usa clases y hojas de estilo por mantenibilidad.

jquery
// get computed style (first matched element)
$('.box').css('color')           // 'rgb(255, 0, 0)'
$('.box').css('font-size')       // '14px'

// set single property
$('.box').css('color', 'red')

// set multiple properties
$('.box').css({
  color: 'red',
  'background-color': '#eee',  // kebab-case needs quotes
  fontSize: '16px',            // or use camelCase
  marginTop: '10px'
})

// setter with callback (index, old value)
$('div').css('width', function (i, old) {
  return (parseInt(old) + 50) + 'px'
})

Manipulación de clases

Las funciones de clase son la forma preferida de estilizar elementos — mantienen la presentación en CSS, no en JS. .addClass, .removeClass y .toggleClass aceptan listas de clases separadas por espacios. .toggleClass(nombre, bool) añade/quita según el booleano — útil para UI guiada por estado. .hasClass(nombre) devuelve un booleano (solo comprueba el primer elemento). Por rendimiento, las clases son mucho más rápidas que .css() para estilos no triviales porque agrupan cambios y dejan optimizar al navegador.

jquery
// add class
$('.box').addClass('active')

// remove class
$('.box').removeClass('active')

// toggle (add if absent, remove if present)
$('.box').toggleClass('active')

// toggle based on boolean
$('.box').toggleClass('active', isValid)

// add/remove multiple (space-separated)
$('.box').addClass('active highlighted urgent')
$('.box').removeClass('active highlighted')

// check if has class (boolean)
if ($('.box').hasClass('active')) { /* ... */ }

// callback form (index, hasClass)
$('div').toggleClass('even', function (i) {
  return i % 2 === 0
})

Ancho y alto

.width()/.height() = caja de contenido (sin padding/borde). .innerWidth()/.innerHeight() = contenido + padding. .outerWidth()/.outerHeight() = contenido + padding + borde. .outerWidth(true) incluye el margen. Los setters aceptan un número (px) o una cadena. Para window/document, usa $(window) para el viewport y $(document) para la página completa. Estos devuelven números (no cadenas como .css('width')), lo cual es cómodo para cálculos.

jquery
// content size (excludes padding, border, margin)
$('.box').width()          // e.g., 200
$('.box').width(300)       // set content width to 300px
$('.box').height()

// inner (content + padding)
$('.box').innerWidth()
$('.box').innerHeight()

// outer (content + padding + border)
$('.box').outerWidth()
$('.box').outerHeight()

// outer including margin
$('.box').outerWidth(true)

// window & document
$(window).width()    // viewport width
$(document).height() // full document height

Posición y offset

.offset() devuelve {top, left} respecto al documento (útil para posicionamiento absoluto o drag-drop). .position() devuelve coordenadas respecto al offset parent (el ancestro más cercano con position: relative/absolute/fixed). .scrollTop()/.scrollLeft() obtienen o fijan la posición de scroll — $(window).scrollTop(0) sube arriba. .offsetParent() encuentra al ancestro posicionado. Son esenciales para animaciones, drag-drop y scroll infinito.

jquery
// .offset(): position relative to document
const off = $('.box').offset()
console.log(off.left, off.top)  // e.g., 100, 50
$('.box').offset({ top: 200, left: 100 })  // set

// .position(): position relative to offset parent
const pos = $('.box').position()
console.log(pos.left, pos.top)

// .scrollTop() / .scrollLeft(): scroll position
$(window).scrollTop()       // how far scrolled down
$(window).scrollTop(0)      // scroll to top
$('.container').scrollTop(100)

// .offsetParent(): nearest positioned ancestor
$('.box').offsetParent()

Scroll y coordenadas

El manejo de scroll es común en navs pegajosos, scroll infinito y animaciones disparadas por scroll. $('html, body').animate({scrollTop: n}) hace scroll suave. Por rendimiento, aplica throttle a los manejadores de scroll (se disparan muchas veces por scroll). El helper isVisible comprueba si un elemento está dentro del viewport — útil para carga diferida de imágenes o disparar animaciones. El IntersectionObserver moderno es más eficiente para detectar visibilidad; considéralo en proyectos nuevos.

jquery
// scroll to top smoothly
$('html, body').animate({ scrollTop: 0 }, 500)

// scroll to an element
const top = $('#section').offset().top
$('html, body').animate({ scrollTop: top }, 500)

// detect scroll position
$(window).on('scroll', function () {
  const scrolled = $(window).scrollTop()
  if (scrolled > 100) {
    $('.nav').addClass('fixed')
  } else {
    $('.nav').removeClass('fixed')
  }
})

// check if element is in viewport
function isVisible($el) {
  const t = $el.offset().top
  const h = $el.outerHeight()
  const wTop = $(window).scrollTop()
  const wH = $(window).height()
  return t >= wTop && (t + h) <= (wTop + wH)
}
06

AJAX

$.ajax (control total)

$.ajax es la función de bajo nivel con control total. method/verbo http, data (se envía como query para GET o body para POST), dataType insinúa la respuesta esperada (auto-parseada). success/error/complete son los hooks de callback heredados. beforeSend permite modificar el xhr (añadir headers). timeout aborta tras N ms. Para código moderno, prefiere fetch() o $.ajax con promesas .done()/.fail() en lugar de los callbacks success/error.

jquery
$.ajax({
  url: '/api/users',
  method: 'GET',                // or 'POST', 'PUT', 'DELETE'
  data: { page: 1, limit: 10 }, // query string or body
  dataType: 'json',             // expected response type
  contentType: 'application/json',
  timeout: 5000,                // ms
  headers: { 'X-Token': 'abc' },
  beforeSend: function (xhr) { /* ... */ },
  success: function (data, status, xhr) {
    console.log('got', data)
  },
  error: function (xhr, status, error) {
    console.error('failed', status, error)
  },
  complete: function (xhr, status) {
    // runs on both success and error
  }
})

Abreviados: $.get y $.post

$.get y $.post son abreviados para peticiones GET/POST simples. La interfaz tipo promesa (.done/.fail/.always) es más limpia que los callbacks success/error — y soporta encadenar varios manejadores .done. Para bodies de petición JSON, debes fijar contentType: 'application/json' Y hacer JSON.stringify de los datos (jQuery no convierte automáticamente objetos a JSON). Ojo: la promesa de jQuery es un Deferred, no una Promise nativa, pero funciona de forma similar en la mayoría de casos.

jquery
// GET request
$.get('/api/users', { page: 1 }, function (data) {
  console.log(data)
}, 'json')

// promise-based (preferred)
$.get('/api/users', { page: 1 })
  .done(function (data) { console.log(data) })
  .fail(function (xhr, status, err) { console.error(err) })

// POST request
$.post('/api/users', { name: 'Alice' })
  .done(function (data) { /* created */ })

// POST JSON
$.ajax({
  url: '/api/users',
  method: 'POST',
  contentType: 'application/json',
  data: JSON.stringify({ name: 'Alice' })
})

Cargar HTML en elementos

.load() es un abreviado especializado: obtiene HTML de una URL y lo inyecta en los elementos coincidentes. La sintaxis 'url #fragmento' carga solo una porción de la respuesta (la parte que coincide con #fragmento). .load() es genial para actualizaciones parciales sin recarga completa — común en SPAs heredadas. Es GET por defecto, POST si pasas data. El callback recibe (responseText, status, xhr). Para apps modernas, fetch + actualización manual del DOM es lo preferido.

jquery
<!-- load HTML from server into element -->
<div id="content">Loading...</div>

<script>
$('#content').load('/partials/header.html')

// load a fragment (selector after URL space)
$('#content').load('/page.html #main')

// with callback (response, status, xhr)
$('#content').load('/page.html', function (resp, status, xhr) {
  if (status === 'error') {
    $('#content').html('Failed to load')
  }
})

// POST with data
$('#content').load('/api', { id: 5 })
</script>

getJSON y getScript

$.getJSON es un abreviado de $.ajax con dataType:'json' — parsea automáticamente la respuesta. El truco '?callback=?' habilita JSONP para peticiones entre dominios (heredado — usa CORS ahora). $.getScript obtiene y ejecuta un archivo JavaScript — útil para cargar con pereza plugins o analítica bajo demanda. Ambos devuelven objetos jqXHR (tipo promesa). Para peticiones entre dominios hoy, asegúrate de que el servidor envía headers CORS; JSONP es una solución pre-CORS con advertencias de seguridad.

jquery
// fetch and parse JSON
$.getJSON('/api/users', { page: 1 })
  .done(function (data) {
    console.log(data.users)
  })
  .fail(function (xhr, status, err) {
    console.error('JSON fetch failed:', err)
  })

// fetch and execute a script
$.getScript('/js/analytics.js')
  .done(function (script, status) {
    console.log('analytics loaded')
    // script is now available
  })
  .fail(function () {
    console.error('script failed')
  })

// JSONP (cross-domain, legacy)
$.getJSON('https://api.example.com/data?callback=?')
  .done(function (data) { /* ... */ })

Eventos AJAX globales y configuración

Los eventos AJAX globales (ajaxStart, ajaxStop, ajaxComplete, ajaxError, ajaxSuccess) se disparan para cada petición AJAX — perfectos para loaders globales y manejo de errores. $.ajaxSetup fija valores por defecto aplicados a todas las llamadas AJAX posteriores (URL base, headers, timeout). .serialize() convierte un formulario en una query string; .serializeArray() devuelve un array de objetos {name, value} — útil para construir JSON o payloads personalizados. Incluye siempre un token CSRF para peticiones que cambian de estado.

jquery
// global ajax event handlers (bind on document)
$(document)
  .ajaxStart(function () { $('#loader').show() })
  .ajaxStop(function () { $('#loader').hide() })
  .ajaxError(function (e, xhr, settings, error) {
    console.error('AJAX error:', settings.url, error)
  })

// default settings for all AJAX
$.ajaxSetup({
  baseURL: '/api',
  timeout: 10000,
  headers: { 'X-CSRF-Token': $('meta[name=csrf]').attr('content') }
})

// now $.get('/users') -> GET /api/users with the headers
$.get('/users').done(/* ... */)

// serialize a form for AJAX
const data = $('form').serialize()       // "name=Alice&age=30"
const arr = $('form').serializeArray()   // [{name, value}, ...]
07

Efectos y animaciones

Show/hide básico

.show()/.hide()/.toggle() cambian display. Sin argumentos, muestran/ocultan al instante. Con una duración, animan width/height/opacity. 'slow' = 600ms, 'fast' = 200ms, o un número en ms. El callback se dispara al completarse la animación. Las animaciones de jQuery usan requestAnimationFrame por defecto (sin tirones). Ojo: .hide() fija display:none; .show() restaura el valor de display original. Para más control, usa .animate() directamente.

jquery
// instantly show/hide/toggle
$('.box').show()
$('.box').hide()
$('.box').toggle()

// animated (duration in ms or 'slow'/'fast')
$('.box').show(400)         // fade in over 400ms
$('.box').hide('slow')      // ~600ms
$('.box').toggle(300)

// with callback (runs when animation completes)
$('.box').hide(300, function () {
  console.log('hidden')
})

// easing (default 'swing', also 'linear' with plugin)
$('.box').hide({ duration: 300, easing: 'linear' })

Fundidos

Las animaciones de fundido solo cambian opacity (display se mantiene). .fadeTo anima hasta una opacidad concreta — útil para atenuar elementos sin ocultarlos por completo. Las animaciones se encolan por elemento: encadenar .fadeOut().fadeIn() las ejecuta secuencialmente, no simultáneamente. Para correrlas en paralelo, usa .animate() con varias propiedades o la opción queue. El fundido es más suave que show/hide para UI guiada por opacidad como las notificaciones.

jquery
// fade in / out / toggle (opacity only)
$('.box').fadeIn(400)
$('.box').fadeOut(400)
$('.box').fadeToggle(400)

// fade to a specific opacity (0.0 - 1.0)
$('.box').fadeTo(400, 0.5)  // 50% opacity

// with callback
$('.box').fadeOut(300, function () {
  // runs after fade out completes
  $(this).remove()
})

// sequence: fade out, then fade in
$('.box')
  .fadeOut(300)
  .fadeIn(300)  // queued automatically

Deslizamientos

El deslizamiento anima height (y display). .slideDown revela un elemento (de display:none a su altura natural), .slideUp lo oculta (colapsa a 0 y luego display:none), .slideToggle alterna el estado. Perfecto para acordeones, desplegables y paneles colapsables. Combinado con siblings() para comportamiento de acordeón (cerrar los demás cuando uno se abre). El deslizamiento es la animación más común de jQuery — suave y amigable con la accesibilidad si se emparéja con ARIA adecuado.

jquery
// slide down (reveal) / up (hide) / toggle
$('.panel').slideDown(400)
$('.panel').slideUp(400)
$('.panel').slideToggle(400)

// accordion pattern
$('.accordion .header').on('click', function () {
  $(this).next('.content').slideToggle(300)
       .siblings('.content').slideUp(300)
})

// callback after slide completes
$('.panel').slideUp(300, function () {
  console.log('panel closed')
})

.animate() personalizado

.animate() interpola propiedades CSS numéricas a lo largo de una duración. Usa valores relativos ('+=50') para cambios incrementales. Los nombres de propiedad deben ir en camelCase (marginLeft, no margin-left). Los colores exigen el plugin jQuery Color o jQuery UI — el núcleo de jQuery solo anima números. La forma de opciones da más control: queue:false corre en paralelo en lugar de secuencialmente. El easing por defecto es 'swing' (ease-out); 'linear' es uniforme. Se pueden animar muchas propiedades en una sola llamada.

jquery
// animate numeric CSS properties
$('.box').animate({
  width: '+=50',       // relative: add 50px
  height: '300px',
  opacity: 0.5,
  marginLeft: '20px',  // camelCase for hyphenated props
  fontSize: '20px'
}, 800, 'swing', function () {
  console.log('animation done')
})

// options object form
$('.box').animate({
  left: 500
}, {
  duration: 1000,
  easing: 'linear',
  complete: function () { /* done */ },
  queue: false  // run immediately, not queued
})

// NOTE: colors can't be animated without jQuery UI / color plugin

Detener y encadenar

.stop() detiene las animaciones; (clearQueue, jumpToEnd) da control. Sin stop, los hovers rápidos apilan animaciones (el elemento sigue animando mucho después de que el ratón salga) — .stop(true) antes de .animate() lo evita. .finish() salta todas las animaciones en cola a su estado final al instante. .delay(ms) inserta una pausa en la cola de animación — útil para secuencias. Emparéja siempre las animaciones de hover con .stop() para evitar una acumulación entrecortada.

jquery
// .stop(): stop current animation
$('.box').stop()              // stop, leave at current state
$('.box').stop(true)          // clear queue too
$('.box').stop(true, true)    // clear queue AND jump to end

// prevent animation buildup on rapid hover
$('.box').hover(function () {
  $(this).stop(true).animate({ width: 300 }, 200)
}, function () {
  $(this).stop(true).animate({ width: 100 }, 200)
})

// .finish(): jump all queued animations to end state
$('.box').finish()

// .delay(): pause between queued animations
$('.box')
  .fadeOut(300)
  .delay(500)        // wait 500ms
  .fadeIn(300)
08

Recorridos

Subir (padres)

Recorrer hacia arriba: .parent() (padre inmediato), .parents() (cada ancestro hasta el documento), .parents(selector) los filtra, .closest(selector) sube y devuelve la primera coincidencia (incluyendo el propio elemento — lo más común para encontrar un componente contenedor). .parentsUntil(selector) devuelve ancestros hasta pero sin incluir la coincidencia. .closest() es el caballo de batalla de los patrones de delegación de eventos — dado un elemento clicado, encuentra su tarjeta/fila/componente contenedor.

jquery
// direct parent
$('#item').parent()

// all ancestors (up to <html> or selector)
$('#item').parents()              // all ancestors
$('#item').parents('.container')  // first .container ancestor

// closest ancestor (incl. self) matching selector
$('#item').closest('.box')  // very common - find enclosing box

// parentsUntil: ancestors up to (not including) match
$('#item').parentsUntil('.wrapper')

// offsetParent: nearest positioned ancestor
$('#item').offsetParent()

Bajar (hijos)

.children() devuelve solo los hijos directos (un nivel abajo); .find() desciende por la jerarquía completa. .find() es el más común — dado un contenedor, encuentra los descendientes coincidentes (por ejemplo, encontrar cada campo de un formulario). .children() es más rápido cuando solo necesitas hijos directos. .contents() incluye nodos de texto y comentarios (útil para procesar texto o iframes). Filtra con un selector en ambos. Acota siempre los recorridos con .find() para no escanear el documento entero.

jquery
// direct children (optionally filtered)
$('#list').children()             // all direct children
$('#list').children('.item')      // direct children with class .item

// all descendants (filtered)
$('#list').find('li')             // all <li> anywhere inside
$('#list').find('.active')        // all .active descendants

// contents: children including text/comment nodes
$('#box').contents()

// first/last child
$('#list').children().first()
$('#list').children().last()

Moverse lateralmente (hermanos)

Recorridos de hermanos: .siblings() (los hermanos completos), .next()/.prev() (inmediato), .nextAll()/.prevAll() (la serie completa en una dirección), .nextUntil()/.prevUntil() (hasta una coincidencia). Filtra con un selector. El clásico patrón de pestaña activa ($(this).addClass('active').siblings().removeClass('active')) usa siblings para reiniciar el estado de los hermanos. Los hermanos comparten el mismo padre — si los elementos están anidados de otra forma, no son hermanos.

jquery
// all siblings (excluding self)
$('#item').siblings()
$('#item').siblings('.active')  // siblings with class .active

// next/prev: immediate sibling
$('#item').next()
$('#item').prev()

// nextAll/prevAll: all following/preceding siblings
$('#item').nextAll()
$('#item').prevAll('.item')

// nextUntil/prevUntil: siblings up to a match
$('#item').nextUntil('.stop')

// common: highlight active tab
$('.tab').on('click', function () {
  $(this).addClass('active').siblings().removeClass('active')
})

Filtrar una selección

Filtrar acota el conjunto actual sin volver a consultar el DOM. .filter(selector) conserva las coincidencias; .not(selector) es el inverso. .has(selector) conserva los elementos que contienen un descendiente coincidente. .eq(n) reduce a un elemento (n negativo cuenta desde el final). .first()/.last() son comodidades. .slice(inicio, fin) toma un rango. Úsalos para refinar una selección tras el recorrido en lugar de escribir selectores complejos — a menudo más claros y rápidos.

jquery
// .filter: keep matching
$('li').filter('.active')
$('li').filter(function (i) { return i % 2 === 0 })  // even index

// .not: remove matching (inverse of filter)
$('li').not('.active')
$('li').not(':first')

// .has: keep elements that contain a descendant
$('div').has('p')  // divs that contain <p>

// .eq: reduce to one element by index
$('li').eq(2)      // 3rd <li> (0-indexed)
$('li').eq(-1)     // last <li>

// .first / .last
$('li').first()
$('li').last()

// .slice: range
$('li').slice(2, 5)  // indices 2, 3, 4

Encadenar con .end() y .addBack()

.end() desapila la pila de recorrido, volviendo al conjunto anterior — esencial para cadenas legibles que recorren y luego siguen trabajando sobre el original. .addBack() (antes .andSelf) fusiona el conjunto actual con el anterior, de modo que el elemento original participa en las operaciones siguientes. Esto te permite construir cadenas potentes de una línea: encontrar hijos, modificarlos, end() de vuelta al padre, modificar el padre. Indenta las cadenas para que la estructura del recorrido quede clara.

jquery
// .end(): pop back to previous set after a traversal
$('ul')              // [ul]
  .find('li')        // [li, li, li]
    .addClass('item')
    .end()           // back to [ul]
  .addClass('has-items')

// .addBack(): include previous set in current
$('ul')
  .children('li')    // [li, li]
    .addClass('item')
    .addBack()       // [li, li, ul]
  .addClass('related')

// without .addBack, the ul would not get .related
// .andSelf (old name) is deprecated, use .addBack
09

Funciones utilitarias

Iteración: $.each y $.map

$.each itera arrays (índice, valor) u objetos (clave, valor) — ojo, el orden de los argumentos es inverso a Array.forEach. Devuelve false para romper. $.map transforma cada ítem en un array nuevo (devuelve null para saltar). $.grep filtra un array. Son las utilidades de iteración pre-ES5 de jQuery; el código moderno suele usar las funciones nativas de Array (forEach, map, filter) en su lugar. La razón principal para usar $.each es iterar objetos planos (Object.entries en JS moderno).

jquery
// $.each: iterate arrays or objects (returns the collection)
$.each([10, 20, 30], function (index, value) {
  console.log(index, value)  // 0 10, 1 20, 2 30
  if (value === 20) return false  // break
})

$.each({ a: 1, b: 2 }, function (key, value) {
  console.log(key, value)  // 'a' 1, 'b' 2
})

// $.map: transform to a new array
const doubled = $.map([1, 2, 3], function (value, index) {
  return value * 2  // [2, 4, 6]
})

// return null/undefined to skip
const evens = $.map([1, 2, 3, 4], function (v) {
  return v % 2 === 0 ? v : null  // [2, 4]
})

// $.grep: filter an array
const evens = $.grep([1, 2, 3, 4], function (v) { return v % 2 === 0 })
// [2, 4]

Comprobación de tipos

$.type devuelve una cadena de tipo en minúsculas (más granular que typeof). $.isArray, $.isFunction, $.isPlainObject, $.isEmptyObject, $.isWindow, $.isNumeric son booleanos de conveniencia. $.isPlainObject distingue un {} plano de instancias como new Date o window. $.isNumeric devuelve true para números finitos y cadenas numéricas (no para hex como '0x1F' en jQuery más nuevo). En JS moderno, Array.isArray y typeof cubren la mayoría de necesidades, pero $.isPlainObject sigue siendo práctico para la seguridad del deep-extend.

jquery
// $.type: detailed type
$.type([])         // 'array'
$.type({})         // 'object'
$.type('hi')       // 'string'
$.type(null)       // 'null'
$.type(undefined)  // 'undefined'
$.type(/regex/)    // 'regexp'

// specific checks (all return boolean)
$.isArray([])           // true
$.isFunction(fn => {})  // true
$.isEmptyObject({})     // true
$.isPlainObject({})     // true (created by {} or new Object)
$.isPlainObject([])     // false
$.isWindow(window)      // true
$.isNumeric('42')       // true (also '0x1F')
$.isNumeric('abc')      // false

// $.isEmptyObject: no own enumerable props
$.isEmptyObject({ a: 1 })  // false

Utilidades de objetos y arrays

$.extend fusiona objetos — las propiedades posteriores sobrescriben a las anteriores. Pasa true como primer argumento para una fusión profunda (recursiva); si no, es superficial. Pasa siempre {} como primer argumento para no mutar la fuente. $.merge concatena arrays (muta al primero). $.inArray es indexOf (devuelve -1 si no se encuentra). $.makeArray convierte objetos tipo array (NodeList, arguments) en arrays verdaderos — el código moderno usa Array.from o el spread [...nl] en su lugar.

jquery
// $.extend: merge objects (mutates first unless deep copy flag)
const defaults = { a: 1, b: 2 }
const options = { b: 3, c: 4 }
const merged = $.extend({}, defaults, options)
// { a: 1, b: 3, c: 4 }  (later overrides earlier)

// deep merge (recurses into nested objects)
const deep = $.extend(true, {},
  { nested: { x: 1, y: 2 } },
  { nested: { y: 3, z: 4 } }
)
// { nested: { x: 1, y: 3, z: 4 } }

// $.merge: combine two arrays (mutates first)
const combined = $.merge([1, 2], [3, 4])  // [1, 2, 3, 4]

// $.inArray: find index (-1 if not found)
const idx = $.inArray(2, [1, 2, 3])  // 1

// $.makeArray: convert array-like to true array
const arr = $.makeArray(document.querySelectorAll('li'))

Utilidades de cadenas y datos

$.trim recorta espacios en blanco (moderno: str.trim()). $.parseHTML convierte una cadena HTML en un array de nodos del DOM — más seguro que $.fn.html para entrada no confiable (evita la ejecución de scripts). $.param serializa un objeto a una query string (inverso del parseo). $.now es Date.now(). $.unique desduplica arrays de elementos del DOM (rara vez necesario hoy). La mayoría tienen equivalentes nativos modernos; los más útiles que quedan son $.param (para datos AJAX) y $.parseHTML.

jquery
// $.trim: remove leading/trailing whitespace
$.trim('  hello  ')  // 'hello'  (use str.trim() in modern code)

// $.parseHTML: parse string to DOM nodes
const nodes = $.parseHTML('<div><p>Hi</p></div>')
// [div] — array of DOM nodes

// $.parseJSON: parse JSON string (use JSON.parse instead)
const obj = $.parseJSON('{"a":1}')

// $.param: serialize object to query string
$.param({ name: 'Alice', age: 30 })
// 'name=Alice&age=30'
$.param({ tags: ['a', 'b'] })
// 'tags%5B%5D=a&tags%5B%5D=b'

// $.now: current timestamp (Date.now equivalent)
$.now()  // 1700000000000

// $.unique: remove duplicates from DOM element array
$.unique($('.box').get())

Almacenamiento de datos ($.data)

$.data / .data() almacena valores arbitrarios asociados a elementos en una caché interna (no visible en el DOM, más rápido que los atributos). .data() también lee automáticamente los atributos data-* (con casteo de tipos: números, booleanos, JSON). Importante: .data(name, value) escribe en la caché, NO en el atributo data-* — usa .attr('data-name', val) para actualizar el atributo en sí. .removeData limpia la entrada de caché. La caché se limpia cuando los elementos se eliminan con .remove(), evitando fugas.

jquery
// store data on an element (private, won't appear in DOM)
$.data(document.getElementById('box'), 'key', { count: 1 })

// read it back
const v = $.data(el, 'key')  // { count: 1 }

//.data() method form (more common)
$('.box').data('key', { count: 1 })
$('.box').data('key')        // { count: 1 }

// auto-parses data-* attributes
// <div class="box" data-id="42" data-name="alice"></div>
$('.box').data('id')    // 42 (auto-cast to number)
$('.box').data('name')  // 'alice'

// remove data
$('.box').removeData('key')

// note: .data() does NOT write back to data-* attrs
// use .attr('data-key', val) to update the attribute
10

Plugins y extensiones

Escribir un plugin

Los plugins extienden $.fn (el prototipo de jQuery) para poder llamarse sobre colecciones. Devuelve siempre this (o el resultado de una función sobre this) para poder encadenar. Dentro del plugin, 'this' es la colección jQuery; dentro de .each(), 'this' es un elemento crudo del DOM. Envuélvelo en un IIFE para aliar $ con seguridad vía jQuery. El patrón de valores por defecto con $.extend es la forma estándar de aceptar opciones con valores sensatos. Publica plugins vía npm o como scripts independientes.

jquery
// basic plugin pattern
(function ($) {
  $.fn.highlight = function (color) {
    // 'this' is the jQuery collection
    return this.css('background', color || 'yellow')
  }
}(jQuery))

// usage
$('.box').highlight('red')
$('.box').highlight()  // default 'yellow'

// options pattern
$.fn.tooltip = function (options) {
  const settings = $.extend({
    position: 'top',
    delay: 200
  }, options)

  return this.each(function () {
    // 'this' is a DOM element here
    // ... tooltip logic ...
  })
}

Plugin con funciones

El patrón de plugin-boilerplate usa un objeto de funciones despachado por el primer argumento: $('.c').counter({ start: 5 }) para inicializar, $('.c').counter('increment') para llamar a una función. El estado vive en $.data. Este patrón fue popular en la era pre-Vue/React para componentes como sliders, modales y datepickers. Hoy, un framework (Vue/React) suele ser mejor elección para UI con estado; pero para aumentar sitios jQuery heredados, este patrón sigue siendo útil y bien entendido.

jquery
// stateful plugin using data + methods
(function ($) {
  $.fn.counter = function (method) {
    const methods = {
      init: function (options) {
        return this.each(function () {
          const $el = $(this)
          $el.data('count', options?.start || 0)
          $el.text($el.data('count'))
        })
      },
      increment: function () {
        return this.each(function () {
          const $el = $(this)
          const c = $el.data('count') + 1
          $el.data('count', c).text(c)
        })
      },
      reset: function () {
        return this.each(function () {
          $(this).data('count', 0).text(0)
        })
      }
    }

    if (methods[method]) {
      return methods[method].apply(this, Array.prototype.slice.call(arguments, 1))
    } else if (typeof method === 'object' || !method) {
      return methods.init.apply(this, arguments)
    } else {
      $.error('Method ' + method + ' does not exist')
    }
  }
}(jQuery))

Usar plugins populares

jQuery UI es la librería compañera oficial para widgets (datepicker, accordion, autocomplete, dialog) e interacciones (draggable, droppable, sortable). Otros plugins populares: DataTables (tablas ricas en funciones), Select2 (selects mejorados), Slick (carruseles), Magnific Popup (modales). Incluye el CSS y el JS del plugin después de jQuery. Inicializa en DOM ready. Muchos plugins soportan una API de funciones como $('#x').plugin('method', args) y actualizaciones de opciones vía plugin('option', name, val).

jquery
<!-- jQuery UI (interactions, widgets, effects) -->
<link rel="stylesheet" href="https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css">
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>

<script>
// datepicker
$('#date').datepicker({ dateFormat: 'yy-mm-dd' })

// draggable / droppable / sortable
$('.item').draggable()
$('.list').sortable()

// dialog
$('<div>Hello</div>').dialog({ modal: true })
</script>

<!-- Other common plugins -->
<!-- DataTables: tables with sorting, search, pagination -->
<!-- Select2: enhanced <select> with search -->
<!-- Slick: carousel/slider -->
<!-- Magnific Popup: lightbox/modal -->

Fábrica de widgets (jQuery UI)

La fábrica de widgets de jQuery UI ($.widget) es una forma estructurada de construir plugins con estado y amigables con la herencia. Te da _create (constructor), _destroy (limpieza), _setOption, _on (enlazado de eventos con auto-limpieza) y _trigger (eventos personalizados). Las opciones se exponen vía la API de funciones: $el.widget('option', name, value). Los eventos personalizados se disparan como nombrewidget + nombreEvento. Para UI compleja con estado en jQuery, la fábrica de widgets es el patrón más robusto — pero considera migrar a Vue/React para código nuevo.

jquery
// create a reusable widget with state + inheritance
$.widget('my.counter', {
  options: { start: 0 },

  _create: function () {
    this.count = this.options.start
    this._refresh()
    this._on(this.element, { click: 'increment' })
  },

  increment: function () {
    this.count++
    this._refresh()
    this._trigger('changed', null, { count: this.count })
  },

  _refresh: function () {
    this.element.text(this.count)
  },

  _destroy: function () {
    this.element.text('')
  }
})

// usage
$('#el').counter({ start: 5 })  // init
$('#el').counter('increment')   // call method
$('#el').on('counterchanged', function (e, data) {
  console.log('count is', data.count)
})
$('#el').counter('destroy')     // cleanup

Buenas prácticas de plugins

Buenas prácticas de plugins: (1) devolver siempre this para poder encadenar; (2) envolver en IIFE por seguridad de $; (3) usar .each() para que el plugin funcione en selecciones de varios elementos; (4) usar espacios de nombres en los eventos (click.myplugin) para que los usuarios puedan desvincular sin afectar a otros; (5) fusionar opciones con $.extend y exponer los valores por defecto para que los usuarios puedan sobrescribirlos globalmente; (6) limpiar en destroy (eventos, datos, modificaciones del DOM); (7) usar espacio de nombres en el nombre del plugin para evitar colisiones; (8) exponer funciones públicas y valores por defecto por flexibilidad.

jquery
// 1. always return this for chainability
$.fn.green = function () { return this.css('color', 'green') }

// 2. use IIFE for $ safety
(function ($) { /* plugin */ })(jQuery)

// 3. iterate with .each() for multi-element support
$.fn.x = function () { return this.each(function () { /* per element */ }) }

// 4. namespace events so users can unbind cleanly
this._on(this.element, { 'click.myplugin': 'handler' })

// 5. accept options via $.extend
const opts = $.extend({}, $.fn.x.defaults, options)
$.fn.x.defaults = { color: 'red' }

// 6. clean up on destroy (events, data, DOM)
// 7. namespace your plugin name to avoid collisions
// 8. provide public methods + defaults accessible for override
11

Atributos y propiedades

Getters y setters de atributos

.attr() lee/escribe atributos HTML (los valores del marcado, siempre cadenas). .prop() lee/escribe propiedades del DOM (estado actual — por ejemplo, la propiedad checked de un checkbox puede diferir de su atributo checked tras la interacción del usuario). Usa .prop() para atributos booleanos (checked, disabled, selected) y .attr() para los demás (href, src, alt, data-*). .data() lee data-* pero guarda los valores en una caché interna preservando los tipos — usa .attr('data-*') si necesitas actualizar el atributo del DOM en sí.

jquery
// .attr: HTML attribute (what's in the markup)
$('img').attr('src')              // get
$('img').attr('src', 'new.jpg')   // set
$('img').attr({                   // set multiple
  src: 'new.jpg',
  alt: 'Photo',
  width: 200
})

// .removeAttr: remove attribute entirely
$('img').removeAttr('alt')

// .prop: DOM property (current state, may differ from attr)
$('input').prop('checked')        // true/false (current state)
$('input').prop('checked', true)  // check it
$('input').prop('disabled', true)

// data-* attributes
$('div').attr('data-id', 42)      // sets the attribute (string)
$('div').data('id', 42)           // stores in cache (typed)

Atributos de datos

.data(name) lee los atributos data-* con conversión automática de tipos (números, booleanos, JSON). Fijar vía .data(name, value) escribe en una caché interna, NO en el atributo — así que .attr('data-name') sigue devolviendo el original. Para actualizar el atributo real del DOM (por ejemplo, para selectores CSS o lectura del lado del servidor), usa .attr('data-name', value). Esta distinción causa bugs si se confunde. .removeData limpia la caché. Nombres en varias palabras: data-foo-bar se convierte en .data('fooBar').

jquery
<!-- HTML -->
<div class="box" data-id="42" data-name="alice" data-active="true" data-config='{"x":1}'></div>

<script>
// .data() reads data-* with auto type conversion
$('.box').data('id')       // 42 (number, not string)
$('.box').data('name')     // 'alice'
$('.box').data('active')   // true (boolean)
$('.box').data('config')   // { x: 1 } (parsed JSON)

// set data (stored in cache, NOT the attribute)
$('.box').data('id', 99)
$('.box').data('id')       // 99
$('.box').attr('data-id')  // still '42' (attribute unchanged)

// to update the attribute itself, use .attr
$('.box').attr('data-id', 99)

// remove data
$('.box').removeData('id')
</script>

Propiedades de formulario

Para el estado del formulario, usa .prop() (propiedades booleanas del DOM) — .prop('checked') refleja el estado actual, mientras que .attr('checked') devuelve el atributo HTML inicial (no se actualiza con la interacción del usuario). .val() obtiene/fija valores de formulario uniformemente. Para radios, encuentra el :checked y lee su .val(). Para multi-select, .val() devuelve un array. .is(':checked') es una comprobación booleana limpia. Estas distinciones importan para la validación y serialización de formularios.

jquery
// checkbox state
$('input[type=checkbox]').prop('checked')     // true/false
$('input[type=checkbox]').prop('checked', true)
$('input[type=checkbox]').is(':checked')      // boolean

// disabled / readonly
$('input').prop('disabled', true)
$('input').prop('readOnly', true)  // note: camelCase

// select value
$('select').val()                  // selected value
$('select').val('option2')         // set selected
$('select option:selected').text() // selected text

// multiple select
$('select[multiple]').val()        // ['a', 'b'] array

// radio: value of checked
$('input[name=gender]:checked').val()

//.prop vs .attr for checkboxes:
// .prop('checked') = current state (changes when clicked)
// .attr('checked') = initial HTML value (doesn't change)

Clase vs atributo

Tres formas de exponer el estado del elemento a CSS y JS: clases (conocidas, .hasClass), atributos data-* (consultables, con valor) y atributos ARIA (accesibles a los lectores de pantalla). Para el estado visual, las clases son lo más simple. Para estado multivalor (data-state='loading|success|error'), data-* es más limpio. Para accesibilidad, usa aria-* (aria-pressed, aria-expanded, aria-busy) — a menudo solapan con el estado visual, así que emparéjalos. Los frameworks modernos lo facilitan, pero en jQuery sé intencional al elegir.

jquery
// adding behavior tags via class
$('.btn').addClass('loading')
// CSS: .btn.loading { opacity: 0.5; pointer-events: none; }

// via data attribute (cleaner for state)
$('.btn').attr('data-state', 'loading')
// CSS: .btn[data-state="loading"] { ... }

// via aria (accessible)
$('.btn').attr('aria-busy', 'true')

// choosing:
// - class: many CSS hooks, well-known
// - data-*: cleaner for state values, queryable
// - aria-*: exposes state to screen readers

// toggling example
$('.btn').on('click', function () {
  const $b = $(this)
  $b.attr('aria-pressed', $b.attr('aria-pressed') !== 'true')
})

Value (campos de formulario)

.val() es el getter/setter universal de valores de formulario — inputs de texto, textareas, selects y (para radios/checkboxes) el valor del marcado. .serialize() produce una cadena con codificación URL; .serializeArray() da un array {name, value} — conviértelo a un objeto plano con .serializeArray().reduce((o, p) => (o[p.name] = p.value, o), {}). Para reiniciar un formulario, llama a la función nativa .reset() sobre el elemento crudo del DOM (jQuery no tiene función .reset()).

jquery
// text input
$('input[type=text]').val()              // get current value
$('input[type=text]').val('new value')   // set

// textarea
$('textarea').val()

// select
$('select').val()                        // selected value
$('select').val('opt2')                  // set
$('select').val(['a', 'b'])              // multi-select set

// checkbox (use prop for state)
$('input[type=checkbox]').prop('checked')

// radio
$('input[type=radio][name=g]:checked').val()

// serialize whole form
$('form').serialize()                    // 'name=Alice&age=30'
$('form').serializeArray()               // [{name, value}]

// reset form
$('form')[0].reset()
12

Dimensiones y posición

Funciones de ancho y alto

Las funciones de ancho/alto devuelven números (px), a diferencia de .css('width') que devuelve cadenas con unidades. .width() = caja de contenido (width CSS). .innerWidth() = contenido + padding. .outerWidth() = contenido + padding + borde. .outerWidth(true) incluye el margen. Para window/document, $(window).width() es el viewport (área visible); $(document).height() es la altura completa de la página (puede ser mayor que el viewport al hacer scroll). Los setters aceptan números (px) o cadenas ('50%', '10em').

jquery
// content box (no padding, border, margin)
$('.box').width()       // 200 (number, px)
$('.box').width(300)    // set to 300px

// inner (content + padding)
$('.box').innerWidth()
$('.box').innerHeight()

// outer (content + padding + border)
$('.box').outerWidth()
$('.box').outerHeight()

// outer + margin
$('.box').outerWidth(true)
$('.box').outerHeight(true)

// window & document
$(window).width()       // viewport width
$(window).height()      // viewport height
$(document).height()    // document height (may exceed viewport)

Position vs offset

.offset() es relativo al documento (coordenadas absolutas — útil para drag-drop, tooltips posicionados en el ratón). .position() es relativo al offset parent (el ancestro más cercano con position:relative/absolute/fixed) — útil para reposicionar dentro de un contenedor. .offsetParent() encuentra a ese ancestro. .scrollTop()/.scrollLeft() obtienen o fijan la posición de scroll — $(window).scrollTop() es el scroll de la página. La distinción entre offset (documento) y position (padre) es crítica para unos cálculos de posicionamiento correctos.

jquery
// .offset(): relative to document (top-left of page)
const o = $('.box').offset()
console.log(o.left, o.top)         // e.g., 100, 200
$('.box').offset({ top: 0, left: 0 })  // move to top-left of page

// .position(): relative to offset parent
const p = $('.box').position()
console.log(p.left, p.top)         // position within parent

// .scrollTop() / .scrollLeft()
$(window).scrollTop()              // how far page is scrolled down
$(window).scrollTop(0)             // scroll to top
$('.container').scrollTop(100)     // scroll inner container

// .offsetParent(): nearest positioned ancestor
$('.box').offsetParent()           // the element .position() is relative to

Helpers de layout responsivo

resize se dispara muchas veces durante un arrastre — aplica debounce con setTimeout para evitar problemas de rendimiento. Añadir clases al body (mobile/desktop) permite que el CSS responda vía body.mobile .nav { ... }. Para código responsivo moderno, prefiere las media queries de CSS para el estilo y window.matchMedia() en JS — son más eficientes y se alinean con los breakpoints de CSS. El enfoque de resize de jQuery está bien para código heredado, pero CSS + matchMedia es el estándar moderno.

jquery
// check viewport width on resize
$(window).on('resize', function () {
  const w = $(window).width()
  if (w < 768) {
    $('body').addClass('mobile').removeClass('desktop')
  } else {
    $('body').addClass('desktop').removeClass('mobile')
  }
}).resize()  // trigger once to initialize

// debounced resize (avoid firing hundreds of times)
let timer
$(window).on('resize', function () {
  clearTimeout(timer)
  timer = setTimeout(function () {
    console.log('resize settled')
  }, 200)
})

// match media (preferred for responsive checks)
if (window.matchMedia('(max-width: 768px)').matches) {
  // mobile
}

Detección de visibilidad de elementos

:visible/:hidden comprueba display, visibility, opacity y dimensiones — jQuery 3+ trata visibility:hidden y opacity:0 como ocultos (las versiones antiguas los trataban como visibles). Para la detección en el viewport, el helper inViewport compara los límites del elemento con la posición de scroll. El código moderno usa IntersectionObserver para esto — es mucho más eficiente (el navegador hace los cálculos, callbacks solo ante cambios) y no requiere listeners de scroll. El enfoque de jQuery funciona pero se dispara en cada evento de scroll.

jquery
// :visible / :hidden pseudo-classes
$('.box').is(':visible')   // boolean
$('.box:visible').doSomething()

// note: visibility:hidden is now :hidden in jQuery 3+
// (display:none, opacity:0, width:0/height:0 are also :hidden)

// is element in viewport?
function inViewport($el) {
  const elTop = $el.offset().top
  const elBottom = elTop + $el.outerHeight()
  const docTop = $(window).scrollTop()
  const docBottom = docTop + $(window).height()
  return elBottom >= docTop && elTop <= docBottom
}

// scroll-triggered reveal
$(window).on('scroll', function () {
  $('.reveal').each(function () {
    if (inViewport($(this))) {
      $(this).addClass('shown')
    }
  })
})

Posición de scroll y animación

Scroll suave: anima scrollTop en html y body (entre navegadores). Resta la altura del header para navs fijos. Scroll infinito: cuando la posición de scroll + la altura del viewport están a menos de N píxeles de la altura del documento, carga más contenido. Parallax: traslada elementos según la posición de scroll. Aplica siempre throttle a los manejadores de scroll (se disparan decenas de veces por segundo) — usa _.throttle, un debounce basado en temporizador o requestAnimationFrame. Alternativas modernas: CSS scroll-behavior:smooth para el scroll, IntersectionObserver para los disparadores.

jquery
// current scroll position
const scrollTop = $(window).scrollTop()

// smooth scroll to top
$('html, body').animate({ scrollTop: 0 }, 500)

// smooth scroll to element
function scrollTo($el, duration) {
  const top = $el.offset().top - 20  // 20px offset for fixed header
  $('html, body').animate({ scrollTop: top }, duration || 500)
}
scrollTo($('#section2'))

// infinite scroll: load more when near bottom
$(window).on('scroll', function () {
  if ($(window).scrollTop() + $(window).height() >= $(document).height() - 100) {
    loadMore()
  }
})

// parallax (simple)
$(window).on('scroll', function () {
  const y = $(window).scrollTop()
  $('.hero').css('transform', 'translateY(' + (y * 0.5) + 'px)')
})
13

Deferred y promesas

Crear un Deferred

$.Deferred es la implementación de promesas de jQuery (anterior a la Promise nativa). Crea uno y luego llama a .resolve(valor) o .reject(motivo) para liquidarlo. .promise() devuelve una vista de solo lectura (los consumidores no pueden resolverlo). La API heredada usa .done/.fail/.always en lugar de .then/.catch. Los Deferreds de jQuery 3+ son thenables, así que await y Promise.resolve funcionan con ellos. Prefiere la Promise nativa para código nuevo — Deferred es relevante principalmente para AJAX y APIs heredadas.

jquery
// create a Deferred (jQuery's promise source)
const deferred = $.Deferred()

// resolve or reject it later
setTimeout(function () {
  if (Math.random() > 0.5) {
    deferred.resolve('success data')
  } else {
    deferred.reject(new Error('failed'))
  }
}, 1000)

// get the promise (read-only view)
const promise = deferred.promise()

// consume it
promise
  .done(function (data) { console.log('done:', data) })
  .fail(function (err) { console.log('fail:', err) })
  .always(function () { console.log('settled') })

When (async en paralelo)

$.when(deferreds...) espera a que múltiples Deferreds/Promises se resuelvan en su totalidad, y luego llama a .done con arrays de cada resultado. Si alguno rechaza, .fail se dispara de inmediato. Este es el patrón async en paralelo (como Promise.all). El callback recibe un array por cada deferred de entrada (cada uno conteniendo [data, status, xhr] para AJAX). Para código moderno, Promise.all + fetch es más limpio y devuelve los valores resueltos directamente. $.when sigue siendo útil en bases de código con mucho jQuery.

jquery
// run multiple async ops in parallel, wait for all
$.when(
  $.get('/api/users'),
  $.get('/api/posts'),
  $.get('/api/comments')
).done(function (usersResp, postsResp, commentsResp) {
  // each arg is [data, status, xhr]
  const users = usersResp[0]
  const posts = postsResp[0]
  console.log('all loaded:', users, posts)
}).fail(function (err) {
  console.error('one failed:', err)
})

// modern equivalent
Promise.all([
  fetch('/api/users').then(r => r.json()),
  fetch('/api/posts').then(r => r.json())
]).then(([users, posts]) => {
  console.log('all loaded:', users, posts)
})

Encadenar .then()

jQuery 3+ alineó .then con la especificación Promises/A+ — toma (onFulfilled, onRejected) y devuelve una promesa nueva, igual que la Promise.then nativa. Puedes encadenar operaciones asíncronas y transformar valores. Devolver una promesa desde .then hace que espere; devolver un valor lo pasa aguas abajo. .catch también está soportado en 3+. En jQuery 1.x/2.x, .then tenía un comportamiento no estándar — usa .pipe en su lugar. Si es posible, actualiza a 3+ y usa .then/.catch para un código asíncrono más limpio.

jquery
// jQuery 3+: .then follows Promises/A+ (like native then)
$.get('/api/users')
  .then(function (users) {
    // transform or chain another async
    return $.get('/api/users/' + users[0].id)
  })
  .then(function (userDetail) {
    console.log('detail:', userDetail)
    return userDetail.name  // pass value downstream
  })
  .then(function (name) {
    console.log('name:', name)
  })
  .catch(function (err) {
    console.error('any error in chain:', err)
  })

// in jQuery 1.x/2.x, .then had different semantics
// use .done/.pipe for old code; .then for new

Interfaz de promesa AJAX

Todas las llamadas $.ajax (y $.get/$.post) devuelven un objeto jqXHR, que es tipo promesa (soporta .done/.fail/.always) y (en jQuery 3+) thenable (así que await y Promise.resolve funcionan). Se pueden adjuntar varios callbacks .done — cada uno se dispara en caso de éxito. .abort() cancela la petición (dispara .fail con status 'abort'). Para código nuevo, haz await de $.ajax(...) o envuélvelo con Promise.resolve() para integrarlo limpiamente con cadenas de Promise nativas y async/await.

jquery
// $.ajax returns a jqXHR (promise-like)
const req = $.ajax({ url: '/api/data', method: 'GET' })

// multiple callbacks on same request
req.done(function (data) { console.log('handler 1', data) })
req.done(function (data) { console.log('handler 2', data) })
req.fail(function (xhr, status, err) { console.error(err) })
req.always(function () { console.log('settled') })

// abort an in-flight request
req.abort()

// convert to native Promise (jQuery 3+)
Promise.resolve(req).then(function (data) {
  console.log('via native promise:', data)
})

// use with async/await (jQuery 3+)
async function getData() {
  try {
    const data = await $.ajax({ url: '/api/data' })
    console.log(data)
  } catch (err) {
    console.error(err)
  }
}

Pipeline de promesas personalizado

Envuelve cualquier operación asíncrona en un Deferred para obtener una promesa: crea, resuelve/rechaza después, devuelve .promise(). Las colecciones jQuery también exponen .promise(), que se resuelve cuando todas las animaciones en cola sobre los elementos se completan — útil para disparar código tras un lote de animaciones. Esto une la cola de animaciones de jQuery con el código basado en promesas, dejándote hacer await de animaciones o encadenarlas con AJAX u otro trabajo asíncrono limpiamente.

jquery
// wrap a callback-based API in a promise
function delay(ms) {
  const d = $.Deferred()
  setTimeout(function () { d.resolve() }, ms)
  return d.promise()
}

// use it
delay(500).then(function () { console.log('500ms passed') })

// animate then continue
$('.box').fadeOut(300).promise().done(function () {
  console.log('fade done')
})

// queue of animations on multiple elements
$('.box').each(function (i) {
  $(this).delay(i * 100).fadeIn().promise()
})

// when animations on a set are done
$('.box').fadeOut().promise().done(function () {
  console.log('all boxes faded')
})
14

Formularios

Eventos de formulario

submit se dispara al enviar el formulario — haz siempre preventDefault para AJAX. input se dispara en cada pulsación (texto) o cambio de valor — genial para validación en vivo o búsqueda mientras se escribe. change se dispara al perder el foco para inputs de texto pero de inmediato para checkboxes, radios y selects. focus/blur se disparan al enfocar el campo. Usa delegación de eventos sobre el formulario para campos añadidos dinámicamente. La distinción 'change' vs 'input' importa: 'input' es en vivo, 'change' es cuando el usuario termina de editar.

jquery
// submit event
$('form').on('submit', function (e) {
  e.preventDefault()  // stop page reload
  const data = $(this).serialize()
  $.post('/api/save', data)
})

// input event (fires on every keystroke/change)
$('input').on('input', function () {
  console.log('current value:', $(this).val())
})

// change event (fires on blur for text, immediately for checkbox/select)
$('select').on('change', function () {
  console.log('selected:', $(this).val())
})

// focus / blur
$('input').on('focus', function () { $(this).addClass('focused') })
$('input').on('blur', function () { $(this).removeClass('focused') })

// delegated (works for dynamically added fields)
$('form').on('input', '.field', function () { /* ... */ })

Serializar datos del formulario

.serialize() produce una cadena con codificación URL lista para los datos AJAX. .serializeArray() da un array {name, value} — conviértelo a un objeto plano con reduce. Ambos respetan el estado actual del formulario (los checkboxes solo se incluyen si están marcados; los selects usan la opción seleccionada). Para checkboxes, el valor es 'on' por defecto salvo que fijes value='algo'. Los campos deshabilitados se excluyen. Es la forma estándar de recoger datos de formulario para un envío AJAX sin recarga completa.

jquery
<!-- form -->
<form id="f">
  <input name="name" value="Alice">
  <input name="email" value="[email protected]">
  <select name="role"><option value="admin" selected>Admin</option></select>
  <input type="checkbox" name="agree" checked>
</form>

<script>
// serialize: URL-encoded string
$('#f').serialize()
// 'name=Alice&email=a%40b.com&role=admin&agree=on'

// serializeArray: array of {name, value}
$('#f').serializeArray()
// [{ name: 'name', value: 'Alice' }, ...]

// convert to plain object
const obj = {}
$('#f').serializeArray().forEach(p => { obj[p.name] = p.value })
// { name: 'Alice', email: '[email protected]', role: 'admin', agree: 'on' }

// or one-liner reduce
const obj2 = $('#f').serializeArray().reduce((o, p) =>
  (o[p.name] = p.value, o), {})
</script>

Validación de formularios

Validación manual: itera los campos obligatorios, comprueba .val(), alterna una clase 'invalid' para el estilo CSS. La regex de correo es una comprobación básica de cordura (la regex completa RFC 5322 es excesiva). Para formularios complejos, usa el jQuery Validation Plugin que ofrece reglas declarativas (class='required email') y mensajes de error consistentes. Valida siempre del lado del cliente por UX Y del lado del servidor por seguridad — la validación del cliente puede evitarse. Los atributos HTML5 (required, type='email', pattern) son la línea base moderna.

jquery
// simple validation
function validate($form) {
  let valid = true
  $form.find('[data-required]').each(function () {
    const $f = $(this)
    if (!$f.val()) {
      $f.addClass('invalid')
      valid = false
    } else {
      $f.removeClass('invalid')
    }
  })
  $form.find('[type=email]').each(function () {
    if (!/^[^@]+@[^@]+\.[^@]+$/.test($(this).val())) {
      $(this).addClass('invalid')
      valid = false
    }
  })
  return valid
}

$('form').on('submit', function (e) {
  e.preventDefault()
  if (validate($(this))) {
    $.post('/api/save', $(this).serialize())
  }
})

Campos de formulario dinámicos

Añade/quita campos de formulario dinámicamente creando elementos con $() y añadiéndolos. Usa nombres estilo array (tags[]) para que el servidor reciba un array. La delegación de eventos (on('click', '.remove', ...)) maneja los clics en los botones de eliminación añadidos dinámicamente. Para campos reordenables (con botones arriba/abajo o drag-drop), renumera los nombres tras cada cambio para que el servidor vea una secuencia limpia. Este patrón es común en inputs de tags, partidas dinámicas y formularios de configuración.

jquery
// add a new field
$('.add-field').on('click', function () {
  const $field = $('<input>', {
    type: 'text',
    name: 'tags[]',
    class: 'tag-input',
    placeholder: 'Tag'
  })
  $('#fields').append($field)
})

// remove a field
$('#fields').on('click', '.remove', function () {
  $(this).closest('.field-row').remove()
})

// array field names (tags[]) — server receives an array
// PHP/Rails auto-parse 'name[]' into arrays

// re-number fields after add/remove
function renumber() {
  $('#fields .field').each(function (i) {
    $(this).find('input').attr('name', 'item_' + i)
  })
}

Envío de formulario AJAX

Un manejador de formularios AJAX reutilizable: serializa el formulario, hace POST a su URL de action, maneja éxito/error. Deshabilita el botón de envío durante la petición para evitar envíos dobles. Dispara eventos personalizados (ajax:success, ajax:error) para que otro código pueda reaccionar. Reinicia el formulario en caso de éxito. Muestra los errores de validación del servidor mapeando nombres de campo a mensajes de error. Este patrón convierte cualquier formulario en un formulario AJAX añadiendo class='ajax' — una mejora común de mejora progresiva.

jquery
// generic AJAX form submission
$('form.ajax').on('submit', function (e) {
  e.preventDefault()
  const $form = $(this)
  const data = $form.serialize()
  const url = $form.attr('action') || window.location.href
  const method = $form.attr('method') || 'POST'

  // show loading state
  $form.find('button').prop('disabled', true).addClass('loading')

  $.ajax({
    url: url,
    method: method,
    data: data,
    dataType: 'json'
  })
  .done(function (resp) {
    $form.trigger('ajax:success', [resp])
    $form[0].reset()
  })
  .fail(function (xhr) {
    $form.trigger('ajax:error', [xhr])
    const errors = xhr.responseJSON?.errors
    if (errors) showErrors($form, errors)
  })
  .always(function () {
    $form.find('button').prop('disabled', false).removeClass('loading')
  })
})
15

Iteración y bucles

$.each vs .each()

$.each es una utilidad genérica que itera arrays (índice, valor) u objetos planos (clave, valor). .each() es una función de las colecciones jQuery — 'this' es el elemento crudo del DOM. Ambos aceptan devolver false para romper y cualquier otra cosa para continuar. Ojo, el orden de los argumentos es (índice, valor) — contrario al (valor, índice) de Array.forEach. Para código moderno, se prefieren los nativos forEach/map/for...of; .each() sigue siendo útil al trabajar con colecciones jQuery y necesitar el elemento como 'this'.

jquery
// $.each: generic iterator (arrays AND objects)
$.each([10, 20, 30], function (index, value) {
  console.log(index, value)  // 0 10, 1 20, 2 30
})

$.each({ a: 1, b: 2 }, function (key, value) {
  console.log(key, value)  // 'a' 1, 'b' 2
})

// .each(): method on jQuery collections only
$('li').each(function (index, element) {
  // 'this' is the DOM element (= element)
  // wrap with $(this) for jQuery methods
  $(this).text(index + ': ' + $(this).text())
})

// breaking out
$('li').each(function (i) {
  if (i === 3) return false  // stop iteration
  // return true (or nothing) to continue
})

$.map vs .map()

$.map transforma un array/objeto en un array nuevo (devuelve null para saltar, devuelve un array para aplanar). Ojo, el orden de los argumentos es (valor, índice) — contrario al de $.each. .map() sobre colecciones jQuery devuelve una nueva colección jQuery (llama a .get() para convertirla a un array plano). Devolver null/undefined desde .map() excluye ese ítem. Estos preceden al Array.map nativo; el código moderno usa el map nativo, pero el .map() de jQuery sigue siendo práctico para extraer valores de colecciones del DOM.

jquery
// $.map: transform an array or object
const doubled = $.map([1, 2, 3], function (value, index) {
  return value * 2  // [2, 4, 6]
})

// returning null/undefined removes the item
const evens = $.map([1, 2, 3, 4], function (v) {
  return v % 2 === 0 ? v : null  // [2, 4]
})

// returning an array flattens it
const flat = $.map([1, 2], function (v) {
  return [v, v * 10]  // [1, 10, 2, 20]
})

// .map() on jQuery collections
const ids = $('li').map(function (index, el) {
  return $(el).data('id')  // jQuery collection of ids
}).get()  // .get() converts to plain array [1, 2, 3]

Bucles con for/while

Para máximo rendimiento con colecciones grandes, usa un bucle for clásico con $items[i] (elemento crudo del DOM) en lugar de $items.eq(i) (envuelto en jQuery) — evita crear un objeto jQuery nuevo por iteración. La propiedad .length funciona directamente. for...of funciona sobre colecciones jQuery (son iterables). Sin embargo, prefiere .each() por legibilidad salvo que hayas medido un problema de rendimiento — la diferencia rara vez se nota salvo con miles de elementos.

jquery
// classic for loop with .eq(i)
const $items = $('li')
for (let i = 0; i < $items.length; i++) {
  const $item = $items.eq(i)
  $item.text('Item ' + i)
}

// or use the raw DOM elements (faster, no jQuery wrapping)
for (let i = 0; i < $items.length; i++) {
  $items[i].textContent = 'Item ' + i  // raw DOM
}

// while loop
let i = 0
while (i < $items.length) {
  $($items[i]).addClass('item-' + i)
  i++
}

// for...of (modern, on the collection)
for (const el of $items) {
  $(el).addClass('processed')
}

Filtrar durante la iteración

Filtra antes de iterar para un código más limpio — $('li').filter('.active').each(...) es más idiomático que condicionales dentro de .each(). Para recoger un subconjunto, empuja los elementos crudos del DOM coincidentes a un array y envuélvelo con $() al final. Para extraer valores, .map().get() es el patrón más limpio. Evita construir colecciones jQuery dentro de bucles (cada llamada $() tiene sobrecarga) — recoge elementos crudos y envuélvelos una vez.

jquery
// filter then iterate
$('li').filter('.active').each(function () {
  $(this).addClass('highlighted')
})

// iterate with conditional logic
$('li').each(function (i) {
  if (i % 2 === 0) {
    $(this).addClass('even')
  } else {
    $(this).addClass('odd')
  }
})

// collect matching items
const active = []
$('li').each(function () {
  if ($(this).hasClass('active')) {
    active.push(this)  // push raw DOM element
  }
})
const $active = $(active)  // wrap in jQuery

// or use .map().get()
const ids = $('li.active').map(function () {
  return $(this).data('id')
}).get()

Anidamiento e iteración compleja

El .each() anidado maneja cuadrículas/matrizes. Para construir DOM a partir de datos, añade a un fragmento de documento e inserta una vez (mucho más rápido que añadir por ítem — cada append dispara reflow). $(document.createDocumentFragment()) crea un fragmento envuelto en jQuery. Para listas muy grandes, considera la concatenación de cadenas + .html() (lo más rápido) o una librería de plantillas. Los frameworks modernos (Vue/React) lo manejan declarativamente, pero el patrón de fragmentos sigue siendo una optimización útil de jQuery.

jquery
// nested iteration over rows and cells
$('table tr').each(function (rowIdx, row) {
  $(row).find('td').each(function (colIdx, cell) {
    $(cell).text('R' + rowIdx + 'C' + colIdx)
  })
})

// iterate over a JSON response and build DOM
$.get('/api/users').done(function (users) {
  const $list = $('#users')
  $.each(users, function (i, user) {
    $list.append(
      $('<li>').text(user.name).data('id', user.id)
    )
  })
})

// build with a document fragment (faster)
const $frag = $(document.createDocumentFragment())
$.each(users, function (i, user) {
  $frag.append('<li>' + user.name + '</li>')
})
$('#users').append($frag)  // one DOM update
16

Almacenamiento y caché de datos

$.data vs .data()

$.data(el, key, val) es la función de bajo nivel sobre un elemento crudo del DOM; .data() es la función cómoda de las colecciones jQuery. Ambos guardan valores en una caché interna (no en el DOM), así que es más rápido que el acceso a atributos. .data() también lee automáticamente los atributos data-* con conversión de tipos (números, booleanos, JSON). Fijar vía .data(key, val) NO actualiza el atributo data-* — usa .attr('data-key', val) para eso. Usa $.removeData(el, key) o .removeData(key) para limpiar.

jquery
// $.data: low-level, on raw DOM element
const el = document.getElementById('box')
$.data(el, 'count', 1)
$.data(el, 'count')       // 1
$.data(el, 'count', 2)
$.data(el, 'count')       // 2
$.removeData(el, 'count')

// .data(): method on jQuery collection (more common)
$('.box').data('count', 1)
$('.box').data('count')   // 1
$('.box').removeData('count')

// auto-reads data-* attributes (with type conversion)
// <div data-id="42" data-active="true"></div>
$('.box').data('id')      // 42 (number)
$('.box').data('active')  // true (boolean)

Guardar estado por elemento

El estado por elemento es la característica estrella de .data() — guarda configuración, contadores, flags u objetos asociados a cada elemento sin contaminar el DOM. Llamar a .data() sin argumentos devuelve el conjunto de datos guardados como objeto. Ojo: guardar un objeto y mutarlo muta la referencia guardada (no hace falta volver a fijarlo). La caché interna se limpia automáticamente cuando los elementos se eliminan vía .remove(), evitando fugas de memoria — pero no si los eliminas con funciones crudas del DOM (parentNode.removeChild).

jquery
// store per-element state on plugin init
$('.counter').each(function () {
  $(this).data('count', 0)
})

// increment on click
$('.counter').on('click', function () {
  const $el = $(this)
  const c = $el.data('count') + 1
  $el.data('count', c)
  $el.text('Count: ' + c)
})

// retrieve all data
const all = $('.counter').data()  // { count: 5, ... }

// store objects
$('.box').data('config', { color: 'red', size: 10 })
$('.box').data('config').color = 'blue'  // mutates the stored object
$('.box').data('config').color  // 'blue'

Cacheando selecciones

Cachear las selecciones jQuery evita volver a consultar el DOM — una mejora de rendimiento significativa en bucles o manejadores frecuentes. Convención: prefija los objetos jQuery cacheados con $ ($boxes, $nav) para distinguirlos de los elementos crudos del DOM. Cuidado: las selecciones cacheadas quedan obsoletas si el DOM cambia (añades/quitas elementos coincidentes). Vuelve a consultar tras insertar contenido dinámico. Para los manejadores de eventos, cachear fuera del manejador (en el mismo ámbito) evita volver a consultar en cada evento.

jquery
// BAD: re-querying the DOM on every use
function update() {
  $('.box').text('updated')     // queries every call
  $('.box').addClass('done')    // queries again
}

// GOOD: cache the selection
const $boxes = $('.box')        // query once
function update() {
  $boxes.text('updated')
  $boxes.addClass('done')
}

// re-query when content changes
$('#container').load('/partial', function () {
  // $boxes is stale — re-query
  const $newBoxes = $('.box')
})

// convention: prefix cached jQuery objects with $
const $nav = $('#nav')
const $items = $('.item')

Atributos data-* de HTML5

Los atributos data-* permiten incrustar configuración en el HTML de forma declarativa — perfectos para la mejora progresiva (el servidor renderiza la configuración, el JS la lee). .data() lee con conversión de tipos (números, booleanos, objetos JSON); .attr() lee la cadena cruda. Los nombres de varias palabras usan kebab-case en HTML (data-foo-bar) y camelCase en JS (.data('fooBar')). Para valores JSON, usa comillas simples en el HTML para envolver el JSON (que usa comillas dobles). Actualizar data-* vía .attr() persiste en el DOM; .data() escribe solo en la caché.

jquery
<!-- declarative config in HTML -->
<div class="widget"
     data-id="42"
     data-mode="advanced"
     data-config='{"timeout":5000,"retries":3}'
     data-enabled="true">
  Widget
</div>

<script>
// .data() reads with type conversion
const $w = $('.widget')
$w.data('id')        // 42 (number)
$w.data('mode')      // 'advanced'
$w.data('config')    // { timeout: 5000, retries: 3 } (parsed JSON)
$w.data('enabled')   // true (boolean)

// .attr() reads raw strings
$w.attr('data-id')   // '42' (string)
$w.attr('data-config') // '{"timeout":5000,...}' (string)

// camelCase mapping: data-foo-bar -> .data('fooBar')
$('[data-foo-bar]').data('fooBar')
</script>

Memoria y limpieza

Usa .remove() para eliminar elementos — limpia automáticamente los datos y eventos asociados. .detach() quita del DOM pero conserva datos/eventos (para reinserción). .empty() elimina los hijos Y limpia sus datos/eventos. NUNCA uses .html('') para vaciar los hijos — no limpia sus datos/eventos, causando fugas de memoria. Para los plugins, expón una función destroy que desvincule los eventos y elimine los datos. La auto-limpieza de jQuery es una razón principal para usar .remove() en lugar de la eliminación cruda del DOM.

jquery
// .remove() cleans up data and events
$('.box').remove()  // safe — data and events gone

// .detach() preserves data and events for re-insertion
const $box = $('.box').detach()
$('#elsewhere').append($box)  // events still fire

// .empty() removes children AND their data/events
$('.container').empty()  // children's data/events cleaned

// .html('') does NOT clean up children's data/events (leak!)
// use .empty() instead

// manual cleanup before removal
$('.box').off().removeData().remove()

// custom cleanup in a plugin
$.fn.myPlugin = function () {
  this.on('click.myplugin', handler)
  this.data('myplugin', { /* state */ })

  // expose destroy for manual cleanup
  // ... or use .on('remove') event (non-standard)
17

Animaciones personalizadas

Fundamentos de .animate()

.animate() interpola propiedades CSS numéricas a lo largo de una duración. Usa valores relativos ('+=50', '-=20') para cambios incrementales. Los nombres de propiedad deben ir en camelCase (marginLeft, no margin-left). Los valores especiales 'toggle', 'show', 'hide' funcionan como sus funciones homólogas. Los números por defecto van en píxeles. Los colores exigen el plugin jQuery Color — el núcleo de jQuery solo anima números. El callback se dispara una vez al completarse la animación (por elemento, así que puede dispararse varias veces para colecciones).

jquery
// animate numeric CSS properties
$('.box').animate({
  width: '500px',
  height: 200,         // number = px
  opacity: 0.5,
  marginLeft: '+=50',  // relative
  fontSize: '20px'     // camelCase for hyphenated props
}, 1000)  // duration in ms

// with callback
$('.box').animate({ left: 300 }, 1000, function () {
  console.log('done')
})

// 'slow' = 600, 'fast' = 200
$('.box').animate({ height: 'toggle' }, 'slow')

// special values: 'toggle', 'show', 'hide'
$('.box').animate({ width: 'toggle' })

Easing y opciones

El easing controla la curva de velocidad: 'swing' (por defecto, inicio/fin lentos, medio rápido) y 'linear' (constante). jQuery UI o el plugin easing añaden 30+ más (easeInOutCubic, easeOutBounce). La forma de opciones da control fino: step se llama en cada fotograma de animación (útil para sincronizar otros elementos), queue:false corre en paralelo (por defecto true encola secuencialmente), specialEasing fija el easing por propiedad. step recibe (now, fx) donde fx tiene fx.prop (nombre de propiedad) y fx.start/fx.end.

jquery
// easing: 'swing' (default, ease-out) or 'linear'
$('.box').animate({ left: 300 }, 1000, 'linear')

// options object form
$('.box').animate({ left: 300 }, {
  duration: 1000,
  easing: 'swing',
  complete: function () { console.log('done') },
  step: function (now, fx) {
    console.log(fx.prop, now)  // called each frame
  },
  queue: true,         // default true (sequential)
  specialEasing: {
    width: 'linear',   // per-property easing
    height: 'swing'
  }
})

// jQuery UI adds more easings: easeInOutCubic, etc.
// or include jquery.easing plugin

Cola de animación

Cada elemento tiene una cola 'fx' — las animaciones sobre el mismo elemento corren secuencialmente por defecto. Usa queue:false para correr en paralelo. .delay(ms) inserta una pausa. .queue(fn) inserta una función personalizada en la cola — llama a next() (o dequeue()) para continuar. Esto te permite mezclar animaciones con código arbitrario (AJAX, callbacks) en una secuencia. .clearQueue() vacía la cola sin afectar a la animación actual. .dequeue() avanza al siguiente ítem en cola.

jquery
// animations queue per element (default)
$('.box')
  .animate({ width: 500 }, 500)  // runs first
  .animate({ height: 300 }, 500) // runs after
  .animate({ opacity: 0.5 }, 500) // runs after that

// total: 1500ms (sequential)

// run in parallel: queue: false
$('.box').animate({ width: 500 }, { duration: 500, queue: false })
$('.box').animate({ height: 300 }, { duration: 500, queue: false })
// both run simultaneously

// .delay(): pause in the queue
$('.box')
  .animate({ width: 500 }, 500)
  .delay(300)              // wait 300ms
  .animate({ height: 300 }, 500)

// .queue(): insert custom function into the queue
$('.box').animate({ width: 500 }, 500).queue(function (next) {
  console.log('between animations')
  next()  // must call to continue
})

Animaciones de color

El núcleo de jQuery no puede animar colores (no son numéricos). El plugin jQuery Color (pequeño e independiente) o jQuery UI añaden soporte de animación de color — backgroundColor, color, borderColor, etc. jQuery UI también habilita animaciones basadas en clases: .addClass('foo', 500) transiciona a los estilos de la clase nueva durante 500ms. Para sitios modernos, prefiere las transiciones CSS (transition: background 0.3s) — están aceleradas por hardware y no requieren JS. Usa la animación de color de jQuery solo por soporte heredado.

jquery
<!-- jQuery core does NOT animate colors -->
<!-- include jQuery Color plugin or jQuery UI -->
<script src="https://code.jquery.com/color/jquery.color-2.2.0.min.js"></script>

<script>
// now color animations work
$('.box').animate({
  backgroundColor: '#ff0000',
  color: '#ffffff',
  borderColor: '#000000'
}, 1000)

// jQuery UI also enables:
// - class animations: .toggleClass('active', 500)
// - more easing functions
// - color transitions on hover
$('.box').hover(function () {
  $(this).animate({ backgroundColor: '#eee' }, 300)
}, function () {
  $(this).animate({ backgroundColor: '#fff' }, 300)
})
</script>

Detener y limpiar

.stop() detiene la animación actual. Con (clearQueue=true), también vacía la cola. Con (jumpToEnd=true), salta la animación actual a su estado final. .finish() salta todas las animaciones en cola a sus estados finales al instante. El selector :animated coincide con los elementos a mitad de animación. Emparéja siempre las animaciones guiadas por hover con .stop(true) para evitar la acumulación cuando el ratón entra/sale rápidamente — sin ella, las animaciones se encolan y se reproducen mucho después de que el ratón salga, causando un comportamiento entrecortado.

jquery
// .stop([clearQueue], [jumpToEnd])
$('.box').stop()              // stop current, stay at current state
$('.box').stop(true)          // also clear the queue
$('.box').stop(true, true)    // clear queue AND jump current to end
$('.box').stop(false, true)   // jump current to end, keep queue

// .finish(): jump ALL queued animations to end state
$('.box').finish()

// prevent hover animation buildup
$('.box').hover(function () {
  $(this).stop(true).animate({ width: 300 }, 200)
}, function () {
  $(this).stop(true).animate({ width: 100 }, 200)
})

// check if currently animating
if (!$(':animated').length) { /* nothing animating */ }
if ($('.box').is(':animated')) { /* still animating */ }
18

Delegación de eventos

¿Por qué delegación?

La delegación de eventos enlaza un manejador a un padre; los clics en los hijos burbujean y lo disparan. Ventajas: (1) un manejador en lugar de N (memoria), (2) funciona automáticamente para elementos añadidos dinámicamente, (3) configuración más rápida (un enlace vs N). El segundo argumento de .on() ('li') es el filtro de selector — 'this' dentro del manejador es el hijo coincidente, no el padre. Usa delegación para cualquier lista, tabla o contenedor donde los hijos compartan comportamiento. El único coste: una ligera sobrecarga por evento (comprobación de selector), que es despreciable.

jquery
// ANTI-PATTERN: bind to each <li> directly
$('li').on('click', function () {
  $(this).toggleClass('done')
})
// - 1 handler PER <li> (100 items = 100 handlers)
// - NEW <li> added later DON'T get the handler
// - high memory, slow setup

// PATTERN: delegate to parent
$('ul').on('click', 'li', function (e) {
  $(this).toggleClass('done')
})
// - 1 handler total
// - works for future <li>
// - low memory, fast setup
// - 'this' is the <li> (not the <ul>)

Delegación en la práctica

Este patrón de lista de tareas muestra el poder de la delegación: dos manejadores delegados en #tasks manejan los botones de borrado y la alternancia de ítems para todos los ítems actuales y futuros. Añadir un <li> nuevo no requiere reenlazar. e.stopPropagation() en el botón de borrado evita que el clic del li también se dispare (lo que alternaría .done al borrar). .closest('li') encuentra el <li> contenedor desde el botón clicado. Este patrón es la base de las SPAs de jQuery antes de los frameworks — y sigue siendo útil para UI tipo widget.

jquery
<!-- dynamic list -->
<ul id="tasks">
  <li>Task 1 <button class="delete">×</button></li>
</ul>

<script>
// ONE delegated handler handles all current AND future items
$('#tasks').on('click', '.delete', function (e) {
  e.stopPropagation()
  $(this).closest('li').remove()
})

$('#tasks').on('click', 'li', function () {
  $(this).toggleClass('done')
})

// adding new items works without re-binding
$('.add').on('click', function () {
  $('#tasks').append('<li>New task <button class="delete">×</button></li>')
})
</script>

Delegado vs enlace directo

El enlace directo adjunta el manejador a los elementos coincidentes; el delegado lo adjunta a un padre y filtra por selector. Diferencia clave dentro del manejador: para directo, e.currentTarget === this === el elemento. Para delegado, e.currentTarget es el padre (donde está enlazado el manejador), this es el hijo coincidente (la coincidencia del selector), y e.target es el elemento realmente clicado (puede ser un descendiente del hijo coincidente). Usa e.delegateTarget para acceder al padre en los manejadores delegados.

jquery
// DIRECT: bind directly to element
// - element must exist at bind time
// - handler attached to element itself
// - e.target === e.currentTarget === this
$('.btn').on('click', function (e) {
  console.log(e.currentTarget === this)  // true
})

// DELEGATED: bind to parent, filter by selector
// - works for future children
// - handler attached to parent
// - e.currentTarget = parent (the bound element)
// - this = child (matched selector)
// - e.target = actual clicked element (may be deeper child)
$('ul').on('click', 'li', function (e) {
  console.log(e.currentTarget)  // the <ul>
  console.log(this)              // the <li>
  console.log(e.target)          // clicked element (maybe <span> in li)
})

Desvincular manejadores delegados

El uso de espacios de nombres (click.task) es la forma más limpia de desvincular manejadores concretos sin afectar a otros. .off('click', 'li') elimina los manejadores delegados que coinciden con ese selector. .off('click') elimina el conjunto de manejadores de clic (directos y delegados). .off() lo elimina por completo — úsalo con cuidado. Para eliminar un manejador concreto, pasa la referencia original de la función. Para plugins, usa siempre espacios de nombres en los eventos (click.myplugin) para que los usuarios puedan desvincular limpiamente sin conocer tus internos.

jquery
// delegate with namespace
$('ul').on('click.task', 'li', handler)

// remove just this delegated handler (by namespace)
$('ul').off('click.task')

// remove all delegated click handlers
$('ul').off('click')

// remove all delegated handlers with a specific selector
$('ul').off('click', 'li')

// remove ALL handlers (including delegated)
$('ul').off()

// remove with reference to the original handler
function handler() { /* ... */ }
$('ul').on('click', 'li', handler)
$('ul').off('click', 'li', handler)  // exact match

Trampas de la delegación

Acota la delegación al ancestro estable más cercano — no centralices la delegación en document/body (cada evento burbujea y se comprueba contra el selector, lo cual es lento). Evita selectores demasiado amplios ('div'). Ten cuidado con stopPropagation en los hijos: impide que se disparen los manejadores delegados de los ancestros. Si un hijo detiene la propagación, el manejador delegado del padre nunca corre. La contrapartida: la delegación es flexible pero añade una mínima sobrecarga por evento (coincidencia de selector) — normalmente despreciable, pero importa en páginas enormes.

jquery
// PITFALL 1: delegated handler on a parent that's too high
$(document).on('click', '.btn', handler)
// works, but EVERY click bubbles to document and is checked
// (slow on large pages — scope to nearest stable parent)

// BETTER: scope to the nearest container that won't be replaced
$('#sidebar').on('click', '.btn', handler)

// PITFALL 2: selector that matches too broadly
$('body').on('click', 'div', handler)  // fires on every div click

// PITFALL 3: stopping propagation in a child breaks delegation
$('.btn').on('click', function (e) {
  e.stopPropagation()  // parent's delegated handler won't fire!
})

// PITFALL 4: delegated handlers don't fire if a parent
// stops propagation before reaching the delegate target
19

Buenas prácticas

Consejos de rendimiento

Consejos de rendimiento clave: (1) cachea las selecciones; (2) acota las consultas a un contenedor con .find(); (3) prefiere los selectores #id (usan getElementById internamente); (4) evita *; (5) delega eventos; (6) agrupa las actualizaciones del DOM mediante fragmentos — cada append dispara reflow, así que construye un fragmento y añade una vez; (7) desmonta (detach) antes de manipular en profundidad (las operaciones sobre elementos desmontados no disparan reflow). Para listas de 1000+ ítems, la concatenación de cadenas + .html() es lo más rápido, pero el fragmento es más limpio.

jquery
// 1. cache selections
const $items = $('.items')  // query once

// 2. scope queries to a container
$('.item', $container)      // search within container
$container.find('.item')    // equivalent, slightly faster

// 3. use ID selectors when possible (fastest)
$('#header')                // getElementById

// 4. avoid universal selector
$('*').doSomething()        // SLOW

// 5. delegate events instead of binding many
$('ul').on('click', 'li', fn)  // 1 handler

// 6. batch DOM updates (use document fragment)
const $frag = $(document.createDocumentFragment())
for (let i = 0; i < 1000; i++) {
  $frag.append('<li>Item ' + i + '</li>')
}
$('ul').append($frag)  // one reflow, not 1000

// 7. detach before heavy manipulation
const $list = $('ul').detach()
// ... modify $list ...
$('#container').append($list)

Rendimiento de la inserción en el DOM

La inserción en el DOM es el mayor cuello de botella de rendimiento. Cada .append() dispara reflow (el navegador recalcula el layout). Para inserciones masivas: (1) construye una cadena HTML y fíjala con .html() (lo más rápido para contenido simple); (2) usa un fragmento de documento y añade una vez (más limpio para elementos complejos); (3) desmonta el contenedor, modifica, vuelve a montar (evita el reflow en el DOM vivo durante la modificación). Para 1000+ ítems, el enfoque de cadenas es significativamente más rápido que .append() por ítem.

jquery
// SLOW: appending in a loop (reflow per iteration)
for (let i = 0; i < 1000; i++) {
  $('ul').append('<li>Item ' + i + '</li>')
}

// FASTER: build string, append once
let html = ''
for (let i = 0; i < 1000; i++) {
  html += '<li>Item ' + i + '</li>'
}
$('ul').html(html)

// FASTEST: detached node + fragment
const $list = $('ul').detach()
const $frag = $(document.createDocumentFragment())
for (let i = 0; i < 1000; i++) {
  $frag.append($('<li>').text('Item ' + i))
}
$list.append($frag).appendTo('#container')

// even faster: array.join
const html = new Array(1000).fill(0).map((_, i) =>
  '<li>Item ' + i + '</li>'
).join('')
$('ul').html(html)

Patrones jQuery modernos

Patrones de jQuery moderno (3.x): usa .on()/.off() (funciones heredadas como .bind/.live/.delegate están eliminadas u obsoletas). Usa la interfaz de promesas (.done/.fail) sobre los callbacks success/error. Acota el código en IIFEs o módulos ES — no contamines los globales. Sáltate $(document).ready si tu script está al final del body. Prefiere las transiciones/animaciones CSS sobre .animate() (aceleradas por hardware, más suaves). Usa 'use strict'. Para proyectos nuevos, evalúa si un framework (Vue/React) es más apropiado que jQuery.

jquery
// use .on() / .off() (not bind/unbind, live, delegate)
$('.btn').on('click', fn)

// use promises (.done/.fail) instead of success/error
$.get('/api').done(fn).fail(errFn)

// use IIFE or modules to scope code
(function ($) {
  'use strict'
  // private code
  $('.btn').on('click', fn)
}(jQuery))

// or ES modules
import $ from 'jquery'
$('.btn').on('click', fn)

// don't pollute global scope
// don't use $(document).ready if script is at end of body

// prefer CSS for animations (hardware-accelerated)
// .css({ transition: 'all 0.3s', transform: 'translateX(100px)' })

Accesibilidad

Esenciales de accesibilidad: añade roles y estados ARIA (role='dialog', aria-modal, aria-expanded, aria-labelledby). Haz que los widgets personalizados sean accesibles por teclado — maneja Enter/Space para botones, flechas para menús, Esc para cerrar modales. Gestiona el foco: mueve el foco dentro de los modales al abrirse, devuélvelo al disparador al cerrarse. Usa elementos semánticos (<button>, <a>, <nav>) en lugar de divs con onclick. Visibilidad: prefiere ocultar vía clases CSS (que los lectores de pantalla pueden ignorar) antes que display:none (que siempre ignoran).

jquery
// add ARIA attributes for screen readers
$('.modal').attr({
  role: 'dialog',
  'aria-modal': true,
  'aria-labelledby': 'modal-title'
})

// toggle aria-expanded for collapsibles
$('.accordion .header').on('click', function () {
  const $h = $(this)
  const expanded = $h.attr('aria-expanded') !== 'true'
  $h.attr('aria-expanded', expanded)
  $h.next('.content').slideToggle()
})

// keyboard navigation
$('.menu-item').on('keydown', function (e) {
  if (e.which === 13 || e.which === 32) {  // Enter or Space
    $(this).trigger('click')
  }
})

// focus management for modals
$('.modal').on('shown', function () {
  $(this).find('input:first').focus()
})

// use button elements for actions (not <div onclick>)
$('<button>').text('Save').on('click', save).appendTo('body')

Seguridad: XSS e inyección HTML

Nunca inyectes cadenas no confiables vía .html() — ejecuta las etiquetas <script> y los manejadores de eventos incrustados (XSS). Usa .text() para texto plano (auto-escapado). Cuando debas incluir HTML, sanea primero (escape manual o una librería como DOMPurify). El patrón más seguro: construye elementos con $() y usa .text() para el contenido dinámico — $('<li>').text(entradaDeUsuario) escapa automáticamente. Ten especial cuidado con los patrones .append('<div>' + data + '</div>') — son vectores de XSS si data está controlada por el usuario.

jquery
// DANGEROUS: injecting untrusted HTML
const userInput = '<script>alert("xss")</script>'
$('.box').html(userInput)        // EXECUTES the script!

// SAFE: escape with .text()
$('.box').text(userInput)        // displays as text, no execution

// SAFE: sanitize before injecting
function escapeHtml(str) {
  return str
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;')
}
$('.box').html(escapeHtml(userInput))

// SAFE: build elements with .text() for content
const $li = $('<li>').text(userInput)  // text is auto-escaped
$('ul').append($li)

// AVOID .html() with user input. Use .text() or DOMPurify.
// $('div').html('<p>' + data + '</p>')  // BAD if data is user input
20

Patrones comunes

Diálogo modal

Un patrón de modal: crea overlay + modal, añádelos al body (escapando los contextos de apilamiento del padre), haz fundido de entrada. Hacer clic en el overlay (no en el modal) lo cierra — usa e.target === this para detectarlo. La tecla Esc cierra. Limpia siempre (elimina el DOM, desvincula los manejadores) al cerrar. Para producción, considera una librería (Magnific Popup, Bootstrap Modal) que maneje la accesibilidad (atrapar el foco, ARIA, devolver el foco al disparador), las animaciones y los modales iframe/ajax. El patrón de arriba es la versión mínima hecha a mano.

jquery
// simple modal pattern
function openModal(html) {
  const $overlay = $('<div class="modal-overlay"></div>')
  const $modal = $('<div class="modal"></div>').html(html)
  $overlay.append($modal).appendTo('body').hide().fadeIn(200)

  $overlay.on('click', function (e) {
    if (e.target === this) closeModal()  // click outside to close
  })

  $(document).on('keydown.modal', function (e) {
    if (e.which === 27) closeModal()  // Esc to close
  })
}

function closeModal() {
  $('.modal-overlay').fadeOut(200, function () { $(this).remove() })
  $(document).off('keydown.modal')
}

// usage
$('.open').on('click', function () {
  openModal('<p>Hello from modal!</p>')
})

Pestañas

Patrón clásico de pestañas: hacer clic en el enlace de una pestaña la activa. El href del enlace (#tab1) se mapea al id del contenido. La clase activa tanto en el enlace como en el contenido controla la visibilidad (CSS: .tab-content:not(.active) { display: none }). El manejador usa delegación de eventos (maneja pestañas añadidas dinámicamente). preventDefault evita que el hash de la URL cambie (o omite preventDefault para habilitar el enlace profundo a pestañas por hash). Por accesibilidad, añade role='tab', aria-selected y navegación con flechas de teclado.

jquery
<!-- HTML -->
<div class="tabs">
  <ul class="tab-nav">
    <li><a href="#tab1" class="active">Tab 1</a></li>
    <li><a href="#tab2">Tab 2</a></li>
    <li><a href="#tab3">Tab 3</a></li>
  </ul>
  <div id="tab1" class="tab-content active">Content 1</div>
  <div id="tab2" class="tab-content">Content 2</div>
  <div id="tab3" class="tab-content">Content 3</div>
</div>

<script>
$('.tab-nav').on('click', 'a', function (e) {
  e.preventDefault()
  const $a = $(this)
  $a.addClass('active').parent().siblings().find('a').removeClass('active')
  $($a.attr('href')).addClass('active').siblings().removeClass('active')
})
</script>

Acordeón

Patrones de acordeón: hacer clic en un encabezado alterna su contenido. La variante de apertura única cierra a los demás cuando uno se abre (elimina el bloque .not($h) para multiapertura). Usa aria-expanded para exponer el estado a los lectores de pantalla — el CSS puede estilizar basándose en él (.acc-header[aria-expanded="true"] { ... }). slideToggle anima el contenido. Usa <button> para los encabezados (accesibles por teclado por defecto). Para muchos ítems, la delegación de eventos en el padre evita enlazar cada encabezado individualmente.

jquery
<!-- HTML -->
<div class="accordion">
  <div class="acc-item">
    <button class="acc-header" aria-expanded="false">Section 1</button>
    <div class="acc-content">Content 1</div>
  </div>
  <!-- more items -->
</div>

<script>
$('.accordion').on('click', '.acc-header', function () {
  const $h = $(this)
  const $c = $h.next('.acc-content')

  // close others (single-open accordion)
  $h.closest('.accordion')
    .find('.acc-header').not($h)
      .attr('aria-expanded', false)
      .next('.acc-content').slideUp()

  // toggle this one
  const isOpen = $h.attr('aria-expanded') === 'true'
  $h.attr('aria-expanded', !isOpen)
  $c.slideToggle()
})
</script>

Scroll infinito

Scroll infinito: detecta cuando el usuario se acerca al fondo, obtiene más ítems y añádelos. Protégete contra cargas concurrentes (flag loading). Cuando el servidor no devuelve más ítems, desvincula el manejador de scroll (sin más intentos). Añade vía fragmento por rendimiento. Aplica throttle al manejador de scroll (se dispara muchas veces por segundo) — bien con un debounce/_.throttle, bien comprobando el flag de carga (como aquí) para saltar mientras hay una petición en curso. Alternativa moderna: IntersectionObserver sobre un elemento centinela al fondo.

jquery
let loading = false
let page = 1

function loadMore() {
  if (loading) return
  loading = true
  $('.loader').show()

  $.get('/api/items', { page: page })
    .done(function (items) {
      if (items.length === 0) {
        // no more items — unbind the scroll handler
        $(window).off('scroll.inf')
        return
      }
      const $frag = $(document.createDocumentFragment())
      items.forEach(item => {
        $frag.append($('<li>').text(item.name))
      })
      $('ul.items').append($frag)
      page++
    })
    .always(function () {
      loading = false
      $('.loader').hide()
    })
}

// trigger when near bottom
$(window).on('scroll.inf', function () {
  if ($(window).scrollTop() + $(window).height() > $(document).height() - 200) {
    loadMore()
  }
})

Búsqueda en vivo (con debounce)

Búsqueda en vivo: a medida que el usuario escribe, consulta al servidor y muestra resultados. El debounce es esencial — sin él, cada pulsación dispara una petición (escritura rápida = decenas de peticiones). El debounce espera N ms tras la última pulsación antes de disparar. 300ms es un buen valor por defecto. Maneja siempre la consulta vacía (limpia los resultados). Para producción, cancela además las peticiones en curso cuando empieza una nueva (usa .abort() sobre el jqXHR anterior) para evitar respuestas fuera de orden. Alternativas modernas: AbortController con fetch.

jquery
// debounce: wait until user pauses typing
function debounce(fn, wait) {
  let timer
  return function () {
    clearTimeout(timer)
    const args = arguments
    const ctx = this
    timer = setTimeout(() => fn.apply(ctx, args), wait)
  }
}

// live search
const $input = $('#search')
const $results = $('#results')

$input.on('input', debounce(function () {
  const q = $(this).val()
  if (!q) { $results.empty(); return }

  $.get('/api/search', { q: q })
    .done(function (items) {
      $results.empty()
      items.forEach(item => {
        $results.append($('<li>').text(item.name))
      })
    })
}, 300))  // wait 300ms after last keystroke

// without debounce, a search fires on every keystroke (too many requests)

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.