Primeiros passos
Incluindo o jQuery
Inclua o jQuery via CDN para carregamento rápido e em cache. A versão minificada (.min.js) é para produção; a não comprimida é para depurar. Sempre forneça um fallback local caso o CDN fique inacessível. Com npm, você pode importar o jQuery como módulo — útil para bundlers como Webpack/Vite. jQuery 3.7.x é a linha atual; IE antigo não é mais suportado.
<!-- 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 -->Document Ready
Envolva código que manipula o DOM em $(document).ready() para que rode apenas depois de a árvore DOM ser interpretada (sem esperar imagens). $(fn) é a abreviação. Se seu <script> está no fim do <body>, o DOM já está disponível e você pode pular o ready. O ready do jQuery é parecido com o DOMContentLoaded — dispara antes do window.load (que espera imagens/iframes).
// 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')
})
})O objeto jQuery ($)
$ é apenas um alias de jQuery — ambos funcionam identicamente. Como função, $ seleciona elementos (retorna uma coleção jQuery). Como namespace, $.foo fornece funções utilitárias. Se outra biblioteca usa $, chame $.noConflict() para liberá-lo; você ainda pode usar jQuery ou passar $ para um callback de ready para ter um alias local.
// $ 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 */ })Encadeamento de funções
A maioria das funções jQuery retorna a mesma coleção jQuery, então você pode encadear chamadas — o recurso de assinatura do jQuery. Use .end() para voltar ao conjunto anterior após uma função de travessia (.find(), .filter()). A indentação torna travessias encadeadas legíveis. Evite cadeias longas demais — ficam difíceis de depurar. Para funções não encadeáveis (como o getter .width()), a cadeia se quebra porque retornam um valor, não a coleção.
// 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 setModo no-conflict
$.noConflict() devolve o controle de $ à biblioteca que o definiu primeiro. Depois de chamar, use o nome completo jQuery, ou atribua jQuery a uma variável personalizada. O padrão IIFE (function($){...})(jQuery) é a forma clássica de manter $ como alias local dentro do seu módulo, deixando o $ global para outras bibliotecas — essencial em WordPress e ambientes legados.
// 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)Seletores
Seletores básicos
O jQuery usa seletores CSS (em sua maioria compatíveis com querySelectorAll). Os três grandes: nome de tag, #id, .class. A vírgula combina seletores (união). #id é o mais rápido (usa getElementById). O universal * é lento — evite em documentos grandes. Os resultados dos seletores são sempre uma coleção jQuery (parecida com array), mesmo que 0 ou 1 elementos casem.
// 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)Hierarquia e combinadores
Combinadores descrevem relações: espaço (descendente), > (filho direto), + (irmão adjacente), ~ (irmãos em geral). A avaliação é da direita para a esquerda, então $('ul li') encontra os <li> primeiro e depois filtra os que estão dentro de <ul> — seletores específicos à direita performam melhor. Evite combinadores profundos em documentos enormes; delimite a um container via $(container).find(...) para melhor desempenho.
// 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')Seletores de atributo
Seletores de atributo miram elementos pelos valores de atributos: [attr] (presença), [attr=val] (exato), [attr^=val] (começa com), [attr$=val] (termina com), [attr*=val] (contém), [attr~=val] (palavra). Coloque valores entre aspas por segurança. [attr!=val] é uma extensão exclusiva do jQuery (use .not('[attr=val]') para conformidade CSS). Útil para formulários (tipos de input), links (padrões de href) e atributos data-*.
// 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"]')Seletores de formulário e input
Pseudo-seletores de formulário (:input, :text, :checked etc.) são extensões do jQuery — não fazem parte do CSS, então não podem usar o caminho rápido do querySelectorAll. Por desempenho em formulários grandes, use $('input[type=text]') em vez de $(':text'). :checked e :selected são essenciais para ler o estado do formulário. São dinâmicos — reavaliam a cada acesso.
// :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')Seletores de filtro e conteúdo
Filtros estreitam uma seleção: :first/:last, :even/:odd (indexado a 0), :eq(n), :gt(n), :lt(n). Filtros de conteúdo (:contains, :has, :empty, :parent) casam com base no conteúdo. :visible e :hidden baseiam-se em offsetWidth/Height e CSS (nota: elementos com visibility:hidden são :hidden no jQuery 3+; antes eram :visible). Muitos são extensões jQuery — prefira as funções .filter(), .first(), .eq() para melhor desempenho.
// 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')Eventos
Vinculando eventos com .on()
.on() é o vinculador de eventos moderno e completo (substituindo .bind/.delegate/.live). Passe nome(s) de evento e um handler. O 'this' dentro do handler é o elemento DOM (não embrulhado em jQuery — envolva com $(this) se precisar). Use namespaces de evento (click.myapp) para desvincular handlers específicos sem afetar outros. Múltiplos eventos podem compartilhar um handler (separados por espaço) ou ter handlers separados (forma de objeto).
// 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 oneDelegação de eventos
A delegação de eventos vincula um handler a um pai que captura eventos dos filhos via bubbling. O segundo seletor do .on() ('li') filtra quais filhos disparam o handler. Benefícios: um handler em vez de N, suporte automático a elementos adicionados dinamicamente, menos memória. Essencial para listas longas ou SPAs. O 'this' é o filho casado (o li), não o pai. Use e.delegateTarget para acessar o pai.
// 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 setupObjeto de evento e funções
O objeto de evento (e) carrega informações e funções de controle. preventDefault impede o comportamento padrão do navegador (navegação de link, submit de formulário). stopPropagation interrompe o bubbling; stopImmediatePropagation também interrompe outros handlers no mesmo elemento. e.target é o elemento realmente clicado (pode ser um filho); e.currentTarget é o elemento com o handler (= this). Passe dados aos handlers via o segundo argumento opcional do .on().
$('.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'
})Funções de evento abreviadas
Funções abreviados (.click, .focus, .submit etc.) vinculam um handler quando chamados com uma função, ou disparam o evento quando chamados sem. .hover(enter, leave) é uma conveniência para mouseenter+mouseleave. Equivalem a .on('evento', fn), mas mais curtos. Algumas abreviações (.load, .error) foram removidas no jQuery 3 — use .on('load', ...). Prefira .on() em código novo; é mais explícito e suporta delegação.
// 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)Disparando eventos e eventos únicos
.trigger('evento') dispara handlers E comportamento nativo (por exemplo, navegação); .triggerHandler() dispara apenas handlers vinculados ao jQuery e retorna o valor de retorno do handler (não encadeável). .one() vincula um handler que se remove sozinho após a primeira invocação — perfeito para dicas de primeiro clique, configuração única. Eventos personalizados permitem comunicação entre componentes: $(document).trigger('myapp:ready') e listeners assinam com .on('myapp:ready', fn).
// 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')Manipulação de DOM
Lendo e definindo conteúdo
.html() funciona com marcação HTML (como innerHTML) — tags são interpretadas. .text() é para texto puro — tags são escapadas e exibidas literalmente (mais seguro contra XSS para entrada de usuário). .val() é para controles de formulário (input, select, textarea). Os três são getters (retornam o valor do primeiro elemento) quando chamados sem argumento, e setters (aplicam aos elementos casados) quando chamados com um. Setters aceitam callback (index, oldValue) => newValue.
// .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-selectInserindo elementos
Crie elementos passando HTML a $(): $('<div class="x">...</div>'). Append/prepend inserem dentro (no fim/início); before/after inserem fora (como irmãos). As variantes 'To' (appendTo, prependTo, insertBefore, insertAfter) invertem o sujeito — úteis para encadear no elemento novo. Elementos recém-inseridos herdam handlers de evento se vinculados via delegação, mas não se vinculados diretamente antes da inserção.
// 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')Removendo e substituindo
.remove() exclui elementos e limpa seus dados/eventos. .detach() remove do DOM mas preserva dados/eventos — útil para realocar elementos temporariamente. .empty() limpa os filhos, mas mantém o elemento. .replaceWith() troca cada elemento por conteúdo novo. .unwrap() remove o pai, promovendo o elemento. Sempre use .remove() ou .detach() — nunca apenas .html('') num pai, que vaza dados/eventos dos filhos.
// 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()Envolvendo e clonando
.wrap() envolve cada elemento individualmente; .wrapAll() envolve o conjunto inteiro como um grupo; .wrapInner() envolve o conteúdo (não o elemento em si). .clone() cria uma cópia profunda — passe true para clonar também handlers de evento e dados (padrão false, para que handlers não disparem na cópia). .unwrap() remove o pai imediato. São poderosos para reestruturar marcação sem reescrever strings HTML.
// 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()Iterando e filtrando
.each() itera — o 'this' é o elemento DOM bruto; retorne false para interromper, qualquer outra coisa para continuar. .map() transforma numa nova coleção jQuery; chame .get() para converter num array simples. .filter() estreita por seletor ou callback; .not() é o inverso. .is() retorna um booleano (algum elemento casa?) — útil em condicionais. Evite loops for com .eq(i); use .each() ou .map() para jQuery idiomático.
// .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 */ }Manipulação de CSS
Lendo e definindo propriedades CSS
.css() lê estilos computados (sempre o valor resolvido, inclusive de regras CSS) ou define estilos inline. Para getters, passe um único nome de propriedade (retorna uma string). Para setters, passe (prop, value) ou um objeto de pares prop:value. Nomes de propriedade podem ser camelCase ou kebab-case (este último precisa de aspas). Valores numéricos assumem pixels para a maioria das propriedades. Evite .css() para layout — use classes e folhas de estilo por manutenibilidade.
// 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'
})Manipulação de classes
Funções de classe são a forma preferida de estilizar elementos — mantêm a apresentação no CSS, não no JS. .addClass, .removeClass, .toggleClass aceitam listas de classes separadas por espaço. .toggleClass(name, bool) adiciona/remove com base no booleano — útil para UI orientada a estado. .hasClass(name) retorna um booleano (verifica apenas o primeiro elemento). Por desempenho, classes são bem mais rápidas que .css() para estilização não trivial, pois agrupam mudanças e deixam o navegador otimizar.
// 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
})Width e height
.width()/.height() = content box (sem padding/borda). .innerWidth()/.innerHeight() = conteúdo + padding. .outerWidth()/.outerHeight() = conteúdo + padding + borda. .outerWidth(true) inclui margem. Setters recebem um número (px) ou string. Para window/document, use $(window) para a viewport e $(document) para a página inteira. Esses retornam números (não strings como .css('width')), o que facilita cálculos.
// 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 heightPosition e offset
.offset() retorna {top, left} relativo ao documento (útil para posicionamento absoluto ou drag-drop). .position() retorna coordenadas relativas ao offset parent (o ancestral mais próximo com position: relative/absolute/fixed). .scrollTop()/.scrollLeft() lêem ou definem a posição de rolagem — $(window).scrollTop(0) rola ao topo. .offsetParent() encontra o ancestral posicionado. Essenciais para animações, drag-drop e scroll infinito.
// .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()Rolagem e coordenadas
Tratamento de rolagem é comum para navs fixas, scroll infinito e animações disparadas por rolagem. $('html, body').animate({scrollTop: n}) rola suavemente. Por desempenho, faça throttle dos handlers de scroll (disparam muitas vezes por rolagem). O auxiliar isVisible verifica se um elemento está na viewport — útil para lazy-loading de imagens ou disparar animações. O IntersectionObserver moderno é mais eficiente para detectar visibilidade; considere-o em projetos novos.
// 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)
}AJAX
$.ajax (controle total)
$.ajax é a função de baixo nível com controle total. method/verbo http, data (enviado como query para GET ou corpo para POST), dataType dá uma dica da resposta esperada (interpretada automaticamente). success/error/complete são os hooks de callback legados. beforeSend permite modificar o xhr (adicionar headers). timeout aborta após N ms. Para código moderno, prefira fetch() ou $.ajax com promises .done()/.fail() em vez dos callbacks success/error.
$.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
}
})Abreviações: $.get e $.post
$.get e $.post são abreviações para requisições GET/POST simples. A interface parecida com promise (.done/.fail/.always) é mais limpa que callbacks success/error — e suporta encadear múltiplos handlers .done. Para corpos de requisição JSON, você precisa definir contentType: 'application/json' E fazer JSON.stringify nos dados (o jQuery não converte objetos para JSON automaticamente). Nota: a promise do jQuery é um Deferred, não uma Promise nativa, mas funciona de forma parecida na maioria dos casos.
// 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' })
})Carregando HTML em elementos
.load() é uma abreviação especializada: busca HTML de uma URL e o injeta nos elementos casados. A sintaxe 'url #fragment' carrega apenas uma parte da resposta (a parte que casa com #fragment). .load() é ótimo para atualizações parciais de página sem recarregar tudo — comum em SPAs legadas. É GET por padrão, POST se você passar data. O callback recebe (responseText, status, xhr). Para apps modernas, fetch + atualização manual do DOM é preferido.
<!-- 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 e getScript
$.getJSON é a abreviação de $.ajax com dataType:'json' — interpreta a resposta automaticamente. O truque '?callback=?' habilita JSONP para requisições cross-domain (legado — use CORS hoje). $.getScript busca e executa um arquivo JavaScript — útil para lazy-loading de plugins ou analytics sob demanda. Ambos retornam objetos jqXHR (parecidos com promise). Para requisições cross-domain hoje, garanta que o servidor envie headers CORS; JSONP é uma solução pré-CORS com ressalvas de segurança.
// 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 globais de AJAX e setup
Eventos globais de AJAX (ajaxStart, ajaxStop, ajaxComplete, ajaxError, ajaxSuccess) disparam para toda requisição AJAX — perfeitos para loaders globais e tratamento de erros. $.ajaxSetup define padrões aplicados a todas as chamadas AJAX subsequentes (URL base, headers, timeout). .serialize() transforma um formulário numa query string; .serializeArray() retorna um array de objetos {name, value} — útil para montar JSON ou payloads personalizados. Sempre inclua um token CSRF para requisições que mudam estado.
// 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}, ...]Efeitos e animações
Show/hide básico
.show()/.hide()/.toggle() mudam o display. Sem argumentos, mostram/ocultam instantaneamente. Com uma duração, animam width/height/opacity. 'slow' = 600ms, 'fast' = 200ms, ou um número em ms. O callback dispara quando a animação completa. Animações jQuery usam requestAnimationFrame por padrão (sem jank). Nota: .hide() define display:none; .show() restaura o valor de display original. Para mais controle, use .animate() diretamente.
// 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' })Fading
Animações de fade só mudam a opacidade (o display permanece). .fadeTo anima até uma opacidade específica — útil para escurecer elementos sem ocultá-los totalmente. Animações entram em fila por elemento: encadear .fadeOut().fadeIn() roda-as em sequência, não simultaneamente. Para rodar em paralelo, use .animate() com múltiplas propriedades ou a opção queue. Fading é mais suave que show/hide para UI dirigida por opacidade, como notificações.
// 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 automaticallySliding
Sliding anima a altura (e o display). .slideDown revela um elemento (de display:none para sua altura natural), .slideUp o oculta (colapsa a 0 e depois display:none), .slideToggle alterna o estado. Perfeito para accordions, dropdowns e painéis colapsáveis. Combinado com siblings() para comportamento de accordion (fecha os outros quando um abre). Sliding é a animação jQuery mais comum — suave e amigável à acessibilidade quando pareada com ARIA adequado.
// 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 propriedades CSS numéricas ao longo de uma duração. Use valores relativos ('+=50') para mudanças incrementais. Nomes de propriedade devem estar em camelCase (marginLeft, não margin-left). Cores exigem o plugin jQuery Color ou jQuery UI — o núcleo do jQuery só anima números. A forma de opções dá mais controle: queue:false roda em paralelo em vez de sequencial. O easing padrão é 'swing' (ease-out); 'linear' é uniforme. Muitas propriedades podem ser animadas numa única chamada.
// 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 pluginParando e encadeando
.stop() interrompe animações; (clearQueue, jumpToEnd) dá controle. Sem stop, hovers rápidos empilham animações (o elemento continua animando muito depois de o mouse sair) — .stop(true) antes de .animate() previne isso. .finish() leva todas as animações em fila ao estado final instantaneamente. .delay(ms) insere uma pausa na fila de animação — útil para sequenciar. Sempre pareie animações de hover com .stop() para evitar acúmulo irregular.
// .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)Travessia
Subindo (parents)
Travessia para cima: .parent() (pai imediato), .parents() (os ancestrais até o document), .parents(selector) filtra-os, .closest(selector) sobe e retorna a primeira correspondência (incluindo o próprio — o mais comum para achar um componente envolvente). .parentsUntil(selector) retorna ancestrais até, mas não incluindo, a correspondência. .closest() é o cavalo de batalha dos padrões de delegação de eventos — dado um elemento clicado, ache seu card/linha/componente envolvente.
// 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()Descendo (children)
.children() retorna apenas filhos diretos (um nível abaixo); .find() desce pelos níveis. .find() é o mais comum — dado um container, acha descendentes correspondentes (por exemplo, achar os campos de formulário dentro de um form). .children() é mais rápido quando você só precisa dos filhos diretos. .contents() inclui nós de texto e comentário (útil para processar texto ou iframes). Filtre com um seletor em ambos. Sempre delimite travessias com .find() para não varrer o documento inteiro.
// 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()Lateralmente (siblings)
Travessias de irmãos: .siblings() (cada irmão), .next()/.prev() (imediato), .nextAll()/.prevAll() (cada um numa direção), .nextUntil()/.prevUntil() (até uma correspondência). Filtre com um seletor. O padrão clássico de aba ativa ($(this).addClass('active').siblings().removeClass('active')) usa siblings para reiniciar o estado dos irmãos. Irmãos compartilham o mesmo pai — se elementos estiverem aninhados de forma diferente, não são irmãos.
// 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')
})Filtrando uma seleção
Filtrar estreita o conjunto atual sem reconsultar o DOM. .filter(selector) mantém as correspondências; .not(selector) é o inverso. .has(selector) mantém elementos que contêm um descendente correspondente. .eq(n) reduz a um elemento (n negativo conta do fim). .first()/.last() são conveniências. .slice(start, end) pega uma faixa. Use-as para refinar uma seleção após a travessia, em vez de escrever seletores complexos — frequentemente mais claro e rápido.
// .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, 4Encadeamento com .end() e .addBack()
.end() desempilha a travessia, voltando ao conjunto anterior — essencial para cadeias legíveis que atravessam e depois continuam trabalhando no original. .addBack() (antes .andSelf) mescla o conjunto atual com o anterior, para que o elemento original participe das operações seguintes. Eles permitem construir cadeias de uma linha poderosas: achar filhos, modificá-los, end() de volta ao pai, modificar o pai. Indente as cadeias para deixar a estrutura da travessia clara.
// .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 .addBackFunções utilitárias
Iteração: $.each e $.map
$.each itera arrays (index, value) ou objetos (key, value) — note que a ordem dos argumentos é invertida em relação a Array.forEach. Retorne false para interromper. $.map transforma cada item num novo array (retorne null para pular). $.grep filtra um array. São os utilitários de iteração pré-ES5 do jQuery; código moderno costuma usar funções nativas de Array (forEach, map, filter). A principal razão de usar $.each é iterar objetos simples (Object.entries no JS moderno).
// $.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]Checagem de tipos
$.type retorna uma string de tipo em minúsculas (mais granular que typeof). $.isArray, $.isFunction, $.isPlainObject, $.isEmptyObject, $.isWindow, $.isNumeric são booleanos de conveniência. $.isPlainObject distingue {} simples de instâncias como new Date ou window. $.isNumeric retorna true para números finitos e strings numéricas (não para hex como '0x1F' no jQuery mais novo). No JS moderno, Array.isArray e typeof cobrem a maioria das necessidades, mas $.isPlainObject ainda é prático para segurança de deep-extend.
// $.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 }) // falseUtilitários de objeto e array
$.extend mescla objetos — propriedades posteriores sobrescrevem as anteriores. Passe true como primeiro argumento para mesclagem profunda (recursiva); caso contrário é rasa. Sempre passe {} como primeiro argumento para não mutar a fonte. $.merge concatena arrays (muta o primeiro). $.inArray é indexOf (retorna -1 se não encontrar). $.makeArray converte objetos parecidos com array (NodeList, arguments) em arrays verdadeiros — código moderno usa Array.from ou spread [...nl].
// $.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'))Utilitários de string e dados
$.trim remove espaços em branco (moderno: str.trim()). $.parseHTML converte uma string HTML num array de nós DOM — mais seguro que $.fn.html para entrada não confiável (evita execução de script). $.param serializa um objeto numa query string (inverso do parse). $.now é Date.now(). $.unique deduplica arrays de elementos DOM (raramente necessário hoje). A maioria tem equivalentes nativos modernos; os mais úteis restantes são $.param (para dados AJAX) e $.parseHTML.
// $.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())Armazenamento de dados ($.data)
$.data / .data() armazena valores arbitrários associados a elementos num cache interno (não visível no DOM, mais rápido que atributos). .data() também lê automaticamente atributos data-* (com cast de tipo: números, booleanos, JSON). Importante: .data(name, value) escreve no cache, NÃO no atributo data-* — use .attr('data-name', val) para atualizar o atributo em si. .removeData limpa a entrada do cache. O cache é limpo quando elementos são removidos com .remove(), prevenindo vazamentos.
// 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 attributePlugins e extensões
Escrevendo um plugin
Plugins estendem $.fn (o protótipo do jQuery) para serem chamáveis em coleções. Sempre retorne this (ou o resultado de uma função sobre this) para encadeabilidade. Dentro do plugin, 'this' é a coleção jQuery; dentro de .each(), 'this' é um elemento DOM bruto. Envolva numa IIFE para aliasar $ via jQuery com segurança. O padrão de defaults com $.extend é a forma padrão de aceitar opções com valores sensatos. Publique plugins via npm ou como scripts independentes.
// 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 com funções
O padrão de plugin-boilerplate usa um objeto de funções despachado pelo primeiro argumento: $('.c').counter({ start: 5 }) para inicializar, $('.c').counter('increment') para chamar uma função. O estado vive em $.data. Esse padrão foi popular na era pré-Vue/React para componentes como sliders, modals, datepickers. Hoje, um framework (Vue/React) costuma ser a melhor escolha para UI com estado; mas para ampliar sites jQuery legados, esse padrão ainda é útil e bem compreendido.
// 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))Usando plugins populares
jQuery UI é a biblioteca companheira oficial para widgets (datepicker, accordion, autocomplete, dialog) e interações (draggable, droppable, sortable). Outros plugins populares: DataTables (tabelas ricas em recursos), Select2 (selects aprimorados), Slick (carousels), Magnific Popup (modals). Inclua o CSS e o JS dos plugins depois do jQuery. Inicialize no DOM ready. Muitos plugins suportam uma API de funções como $('#x').plugin('method', args) e atualizações de opções via plugin('option', name, val).
<!-- 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 -->Widget Factory (jQuery UI)
A Widget Factory do jQuery UI ($.widget) é uma forma estruturada de construir plugins com estado e herança amigáveis. Fornece _create (construtor), _destroy (limpeza), _setOption, _on (vinculação de eventos com limpeza automática), _trigger (eventos personalizados). As opções são expostas via a API de funções: $el.widget('option', name, value). Eventos personalizados disparam como widgetname + eventname. Para UI complexa com estado em jQuery, a widget factory é o padrão mais robusto — mas considere migrar para Vue/React em código novo.
// 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') // cleanupBoas práticas de plugins
Boas práticas de plugins: (1) sempre retorne this para encadeabilidade; (2) envolva numa IIFE para segurança do $; (3) use .each() para que o plugin funcione em seleções multi-elemento; (4) namespace eventos (click.myplugin) para que usuários possam desvincular sem afetar outros; (5) mescle opções com $.extend e exponha defaults para que usuários possam sobrescrever globalmente; (6) limpe no destroy (eventos, dados, modificações de DOM); (7) namespace o nome do plugin para evitar colisões; (8) exponha funções públicas e defaults para flexibilidade.
// 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 overrideAtributos e propriedades
Getters e setters de atributo
.attr() lê/escreve atributos HTML (os valores da marcação, sempre strings). .prop() lê/escreve propriedades DOM (estado atual — por exemplo, a propriedade checked de um checkbox pode diferir do seu atributo checked após interação do usuário). Use .prop() para atributos booleanos (checked, disabled, selected) e .attr() para os demais (href, src, alt, data-*). .data() lê data-* mas armazena valores num cache interno com preservação de tipo — use .attr('data-*') se precisar atualizar o atributo DOM em si.
// .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 data
.data(name) lê atributos data-* com conversão automática de tipo (números, booleanos, JSON). Definir via .data(name, value) escreve num cache interno, NÃO no atributo — então .attr('data-name') ainda retorna o original. Para atualizar o atributo DOM real (por exemplo, para seletores CSS ou leitura no servidor), use .attr('data-name', value). Essa distinção causa bugs se confundida. .removeData limpa o cache. Nomes em camel case: data-foo-bar vira .data('fooBar').
<!-- 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>Propriedades de formulário
Para estado de formulário, use .prop() (propriedades DOM booleanas) — .prop('checked') reflete o estado atual, enquanto .attr('checked') retorna o atributo HTML inicial (não atualiza com interação do usuário). .val() lê/define valores de formulário uniformemente. Para radios, ache o :checked e leia seu .val(). Para multi-select, .val() retorna um array. .is(':checked') é uma checagem booleana limpa. Essas distinções importam para validação e serialização de formulários.
// 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)Classe vs atributo
Três formas de expor estado de elemento ao CSS e ao JS: classes (conhecidas, .hasClass), atributos data-* (consultáveis, carregam valores) e atributos ARIA (acessíveis a leitores de tela). Para estado visual, classes são as mais simples. Para estado multi-valor (data-state='loading|success|error'), data-* é mais limpo. Para acessibilidade, use aria-* (aria-pressed, aria-expanded, aria-busy) — frequentemente se sobrepõem ao estado visual, então pareie-os. Frameworks modernos facilitam isso, mas no jQuery, seja intencional na escolha.
// 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 formulário)
.val() é o getter/setter universal de valores de formulário — inputs de texto, textareas, selects e (para radios/checkboxes) o valor do marcado. .serialize() produz uma string URL-codificada; .serializeArray() dá um array {name, value} — converta num objeto simples com .serializeArray().reduce((o, p) => (o[p.name] = p.value, o), {}). Para reiniciar um formulário, chame a função nativo .reset() no elemento DOM bruto (o jQuery não tem função .reset()).
// 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()Dimensões e posição
Funções de width e height
Funções de width/height retornam números (px), diferente de .css('width') que retorna strings com unidades. .width() = content box (CSS width). .innerWidth() = conteúdo + padding. .outerWidth() = conteúdo + padding + borda. .outerWidth(true) inclui margem. Para window/document, $(window).width() é a viewport (área visível); $(document).height() é a altura total da página (pode ser maior que a viewport ao rolar). Setters recebem números (px) ou strings ('50%', '10em').
// 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() é relativo ao documento (coordenadas absolutas — útil para drag-drop, tooltips posicionados no mouse). .position() é relativo ao offset parent (o ancestral mais próximo com position:relative/absolute/fixed) — útil para reposicionar dentro de um container. .offsetParent() acha esse ancestral. .scrollTop()/.scrollLeft() lêem ou definem a posição de rolagem — $(window).scrollTop() é a rolagem da página. A distinção entre offset (documento) e position (pai) é crítica para cálculos de posicionamento corretos.
// .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 toAuxiliares de layout responsivo
Resize dispara muitas vezes durante um arraste — faça debounce com setTimeout para evitar problemas de desempenho. Adicionar classes ao body (mobile/desktop) permite que o CSS responda via body.mobile .nav { ... }. Para código responsivo moderno, prefira media queries CSS para estilização e window.matchMedia() em JS — são mais performáticos e alinham-se aos breakpoints CSS. A abordagem de resize do jQuery serve para código legado, mas CSS + matchMedia é o padrão moderno.
// 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
}Detecção de visibilidade de elemento
:visible/:hidden verificam display, visibility, opacidade e dimensões — o jQuery 3+ trata visibility:hidden e opacity:0 como hidden (versões antigas os tratavam como visible). Para detecção de viewport, o auxiliar inViewport compara os limites do elemento com a posição de rolagem. Código moderno usa IntersectionObserver para isso — muito mais eficiente (o navegador faz o cálculo, callbacks só em mudanças) e não exige listeners de scroll. A abordagem jQuery funciona, mas dispara a cada evento de scroll.
// :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')
}
})
})Posição de rolagem e animação
Rolagem suave: anime scrollTop tanto em html quanto em body (cross-browser). Subtraia a altura do header para navs fixos. Scroll infinito: quando posição de rolagem + altura da viewport estiver a N pixels da altura do documento, carregue mais conteúdo. Parallax: translade elementos com base na posição de rolagem. Sempre faça throttle dos handlers de scroll (disparam dezenas de vezes por segundo) — use _.throttle, um debounce com timer, ou requestAnimationFrame. Alternativas modernas: CSS scroll-behavior:smooth para rolagem, IntersectionObserver para gatilhos.
// 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)')
})Deferred e promises
Criando um Deferred
$.Deferred é a implementação de promise do jQuery (antecede a Promise nativa). Crie um, depois chame .resolve(value) ou .reject(reason) para assentá-lo. .promise() retorna uma visão somente leitura (consumidores não podem resolvê-lo). A API legada usa .done/.fail/.always em vez de .then/.catch. Deferreds do jQuery 3+ são thenable, então await e Promise.resolve funcionam com eles. Prefira Promise nativa em código novo — Deferred é relevante principalmente para AJAX e APIs legadas.
// 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 paralelo)
$.when(deferreds...) espera que múltiplos Deferreds/Promises se resolvam por completo, e então chama .done com arrays de cada resultado. Se algum rejeitar, .fail dispara imediatamente. É o padrão de async paralelo (como Promise.all). O callback recebe um array por deferred de entrada (cada um contendo [data, status, xhr] para AJAX). Para código moderno, Promise.all + fetch é mais limpo e retorna valores resolvidos diretamente. $.when ainda é útil em bases de código com muito 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)
})Encadeando .then()
O jQuery 3+ alinhou .then à spec Promises/A+ — recebe (onFulfilled, onRejected) e retorna uma nova promise, exatamente como Promise.then nativa. Você pode encadear operações assíncronas e transformar valores. Retornar uma promise de .then espera por ela; retornar um valor o passa adiante. .catch também é suportado na 3+. Para jQuery 1.x/2.x, .then tinha comportamento não padrão — use .pipe. Se possível, atualize para 3+ e use .then/.catch para código assíncrono mais limpo.
// 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 newInterface de promise do AJAX
Todas as chamadas $.ajax (e $.get/$.post) retornam um objeto jqXHR, que é parecido com promise (suporta .done/.fail/.always) e (no jQuery 3+) thenable (então await e Promise.resolve funcionam). Múltiplos callbacks .done podem ser anexados — cada um dispara em sucesso. .abort() cancela a requisição (dispara .fail com status 'abort'). Para código novo, faça await em $.ajax(...) ou envolva com Promise.resolve() para integrar com cadeias nativas de Promise e async/await de forma limpa.
// $.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 promise personalizado
Envolva qualquer operação assíncrona num Deferred para obter uma promise: crie, resolve/reject mais tarde, retorne .promise(). Coleções jQuery também expõem .promise() que se resolve quando todas as animações enfileiradas nos elementos completam — útil para disparar código após um lote de animações. Isso liga a fila de animação do jQuery ao código baseado em promise, permitindo fazer await de animações ou encadeá-las com AJAX ou outro trabalho assíncrono de forma limpa.
// 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')
})Formulários
Eventos de formulário
submit dispara ao enviar o formulário — sempre preventDefault para AJAX. input dispara a cada tecla (texto) ou mudança de valor — ótimo para validação ao vivo ou busca enquanto digita. change dispara ao perder o foco para inputs de texto, mas imediatamente para checkboxes, radios e selects. focus/blur disparam ao focar o campo. Use delegação de eventos no formulário para campos adicionados dinamicamente. A distinção 'change' vs 'input' importa: 'input' é ao vivo, 'change' é quando o usuário termina de editar.
// 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 () { /* ... */ })Serializando dados do formulário
.serialize() produz uma string URL-codificada pronta para dados AJAX. .serializeArray() dá um array {name, value} — converta num objeto simples com reduce. Ambos respeitam o estado atual do formulário (checkboxes só entram se marcados; selects usam a opção selecionada). Para checkboxes, o valor é 'on' por padrão, a menos que você defina value='algo'. Campos desabilitados são excluídos. Essa é a forma padrão de coletar dados de formulário para envio AJAX sem recarregar a página.
<!-- 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>Validação de formulário
Validação manual: itere os campos obrigatórios, verifique .val(), alterne uma classe 'invalid' para estilização CSS. Regex de e-mail é uma checagem básica de sanidade (a regex completa da RFC 5322 é exagero). Para formulários complexos, use o jQuery Validation Plugin, que fornece regras declarativas (class='required email') e mensagens de erro consistentes. Sempre valide no cliente pela UX E no servidor pela segurança — a validação no cliente pode ser burlada. Atributos HTML5 (required, type='email', pattern) são a base moderna.
// 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 formulário dinâmicos
Adicione/remova campos de formulário dinamicamente criando elementos com $() e anexando. Use nomes estilo array (tags[]) para que o servidor receba um array. Delegação de eventos (on('click', '.remove', ...)) trata cliques em botões de remoção adicionados dinamicamente. Para campos reordenáveis (com botões subir/descer ou drag-drop), renumere os nomes após cada mudança para que o servidor veja uma sequência limpa. Esse padrão é comum para inputs de tags, itens de linha dinâmicos e formulários de configuração.
// 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)
})
}Envio de formulário via AJAX
Um handler de formulário AJAX reutilizável: serialize o formulário, POST para a URL de action dele, trate sucesso/erro. Desabilite o botão de submit durante a requisição para prevenir envios duplicados. Dispare eventos personalizados (ajax:success, ajax:error) para que outro código possa reagir. Reinicie o formulário em sucesso. Mostre erros de validação do servidor mapeando nomes de campos a mensagens. Esse padrão transforma qualquer formulário num formulário AJAX adicionando class='ajax' — um aprimoramento progressivo comum.
// 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')
})
})Iteração e loops
$.each vs .each()
$.each é um utilitário genérico que itera arrays (index, value) ou objetos simples (key, value). .each() é uma função em coleções jQuery — o 'this' é o elemento DOM bruto. Ambos aceitam return false para interromper e qualquer outra coisa para continuar. Note que a ordem dos argumentos é (index, value) — o oposto de Array.forEach, que é (value, index). Para código moderno, forEach/map/for...of nativos são preferidos; .each() continua útil ao trabalhar com coleções jQuery e precisar do elemento como 'this'.
// $.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 um array/objeto num novo array (retorne null para pular, retorne um array para achatar). Note que a ordem dos argumentos é (value, index) — o oposto de $.each. .map() em coleções jQuery retorna uma nova coleção jQuery (chame .get() para converter num array simples). Retornar null/undefined de .map() exclui aquele item. Esses antecedem o Array.map nativo; código moderno usa map nativo, mas o .map() do jQuery ainda é prático para extrair valores de coleções DOM.
// $.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]Loops com for/while
Para desempenho bruto com coleções grandes, use um loop for clássico com $items[i] (elemento DOM bruto) em vez de $items.eq(i) (embrulhado em jQuery) — evita criar um novo objeto jQuery por iteração. A propriedade .length funciona diretamente. for...of funciona em coleções jQuery (são iteráveis). Porém, prefira .each() por legibilidade, a menos que tenha medido um problema de desempenho — a diferença raramente é perceptível, exceto com milhares de elementos.
// 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')
}Filtrando durante a iteração
Filtre antes de iterar para um código mais limpo — $('li').filter('.active').each(...) é mais idiomático que condicionais dentro de .each(). Para coletar um subconjunto, empurre elementos DOM brutos correspondentes num array e embrulhe com $() no fim. Para extração de valores, .map().get() é o padrão mais limpo. Evite construir coleções jQuery em loops (cada chamada $() tem overhead) — colete elementos brutos e embrulhe uma vez.
// 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()Aninhamento e iteração complexa
.each() aninhado trata grids/matrices. Para construir DOM a partir de dados, anexe a um document fragment e insira uma vez (bem mais rápido que anexar por item — cada append dispara reflow). $(document.createDocumentFragment()) cria um fragment embrulhado em jQuery. Para listas muito grandes, considere concatenação de strings + .html() (o mais rápido) ou uma biblioteca de templates. Frameworks modernos (Vue/React) fazem isso declarativamente, mas o padrão de fragment continua sendo uma otimização jQuery útil.
// 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 updateArmazenamento de dados e cache
$.data vs .data()
$.data(el, key, val) é a função de baixo nível sobre um elemento DOM bruto; .data() é a função conveniente em coleções jQuery. Ambos armazenam valores num cache interno (não no DOM), então é mais rápido que acesso a atributos. .data() também lê automaticamente atributos data-* com conversão de tipo (números, booleanos, JSON). Definir via .data(key, val) NÃO atualiza o atributo data-* — use .attr('data-key', val) para isso. Use $.removeData(el, key) ou .removeData(key) para limpar.
// $.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)Armazenando estado por elemento
Estado por elemento é o recurso matador de .data() — armazene config, contadores, flags ou objetos associados a cada elemento sem poluir o DOM. Chamar .data() sem argumentos retorna os dados armazenados como objeto. Note que armazenar um objeto e mutá-lo muta a referência armazenada (não precisa redefinir). O cache interno é limpo automaticamente quando elementos são removidos via .remove(), prevenindo vazamentos de memória — mas não se você os remover via funções DOM brutos (parentNode.removeChild).
// 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 seleções
Cacheiar seleções jQuery evita reconsultar o DOM — uma vitória significativa de desempenho em loops ou handlers frequentes. Convenção: prefixe objetos jQuery em cache com $ ($boxes, $nav) para distingui-los de elementos DOM brutos. Cuidado: seleções em cache ficam obsoletas se o DOM mudar (você adiciona/remove elementos correspondentes). Reconsulte após inserção de conteúdo dinâmico. Para handlers de evento, cachear fora do handler (no mesmo escopo) evita reconsultar a cada evento.
// 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-* do HTML5
Atributos data-* permitem embutir config no HTML declarativamente — perfeitos para aprimoramento progressivo (o servidor renderiza a config, o JS lê). .data() lê com conversão de tipo (números, booleanos, objetos JSON); .attr() lê a string bruta. Nomes de múltiplas palavras usam kebab-case no HTML (data-foo-bar) e camelCase no JS (.data('fooBar')). Para valores JSON, use aspas simples no HTML para envolver o JSON (que usa aspas duplas). Atualizar data-* via .attr() persiste no DOM; .data() escreve só no cache.
<!-- 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>Memória e limpeza
Use .remove() para excluir elementos — ele limpa dados e eventos associados automaticamente. .detach() remove do DOM, mas preserva dados/eventos (para reinserção). .empty() remove os filhos E limpa seus dados/eventos. NUNCA use .html('') para limpar filhos — não limpa seus dados/eventos, causando vazamentos de memória. Para plugins, exponha uma função destroy que desvincula eventos e remove dados. A limpeza automática do jQuery é uma grande razão para usar .remove() em vez de remoção DOM bruta.
// .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)Animações personalizadas
Básico do .animate()
.animate() interpola propriedades CSS numéricas ao longo de uma duração. Use valores relativos ('+=50', '-=20') para mudanças incrementais. Nomes de propriedade devem estar em camelCase (marginLeft, não margin-left). Valores especiais 'toggle', 'show', 'hide' funcionam como suas contrapartes de função. Números assumem pixels. Cores exigem o plugin jQuery Color — o núcleo do jQuery só anima números. O callback dispara uma vez quando a animação completa (por elemento, então pode disparar várias vezes para coleções).
// 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 e opções
Easing controla a curva de velocidade: 'swing' (padrão, início/fim lentos, meio rápido) e 'linear' (constante). jQuery UI ou o plugin easing adicionam 30+ mais (easeInOutCubic, easeOutBounce). A forma de opções dá controle fino: step é chamado a cada frame de animação (útil para sincronizar outros elementos), queue:false roda em paralelo (o padrão true enfileira sequencialmente), specialEasing define easing por propriedade. step recebe (now, fx), em que fx tem fx.prop (nome da propriedade) e fx.start/fx.end.
// 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 pluginFila de animação
Cada elemento tem uma fila 'fx' — animações no mesmo elemento rodam em sequência por padrão. Use queue:false para rodar em paralelo. .delay(ms) insere uma pausa. .queue(fn) insere uma função personalizada na fila — chame next() (ou dequeue()) para continuar. Isso permite misturar animações com código arbitrário (AJAX, callbacks) numa sequência. .clearQueue() esvazia a fila sem afetar a animação atual. .dequeue() avança ao próximo item da fila.
// 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
})Animações de cor
O núcleo do jQuery não consegue animar cores (não são numéricas). O plugin jQuery Color (pequeno, independente) ou o jQuery UI adicionam suporte a animação de cor — backgroundColor, color, borderColor etc. jQuery UI também habilita animações baseadas em classe: .addClass('foo', 500) transiciona para os estilos da nova classe em 500ms. Para sites modernos, prefira transições CSS (transition: background 0.3s) — são aceleradas por hardware e não exigem JS. Use animação de cor do jQuery só para suporte legado.
<!-- 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>Parando e limpando
.stop() interrompe a animação atual. Com (clearQueue=true), também esvazia a fila. Com (jumpToEnd=true), salta a animação atual ao estado final. .finish() leva todas as animações em fila aos estados finais instantaneamente. O seletor :animated casa elementos no meio de animação. Sempre pareie animações dirigidas por hover com .stop(true) para evitar acúmulo quando o mouse entra/sai rapidamente — sem isso, as animações se enfileiram e tocam muito depois de o mouse sair, causando comportamento irregular.
// .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 */ }Delegação de eventos
Por que delegação?
A delegação de eventos vincula um handler a um pai; cliques nos filhos sobem por bubbling e o disparam. Benefícios: (1) um handler em vez de N (memória), (2) funciona automaticamente para elementos adicionados dinamicamente, (3) configuração mais rápida (um bind vs N). O segundo argumento do .on() ('li') é o filtro de seletor — o 'this' dentro do handler é o filho casado, não o pai. Use delegação para qualquer lista, tabela ou container em que filhos compartilham comportamento. O único custo: leve overhead por evento (checagem de seletor), desprezível.
// 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>)Delegação na prática
Esse padrão de todo-list mostra o poder da delegação: dois handlers delegados em #tasks tratam botões de exclusão e alternância de itens para os itens atuais e futuros. Adicionar um novo <li> não exige re-vinculação. e.stopPropagation() no botão de excluir impede que o clique no li também dispare (o que alternaria .done ao excluir). .closest('li') acha o <li> envolvente a partir do botão clicado. Esse padrão é a fundação das SPAs jQuery antes dos frameworks — e ainda útil para UIs tipo widget.
<!-- 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 vinculação direta
A vinculação direta anexa o handler aos elementos casados; a delegada anexa a um pai e filtra por seletor. Diferença-chave dentro do handler: para direta, e.currentTarget === this === o elemento. Para delegada, e.currentTarget é o pai (onde o handler está vinculado), this é o filho casado (a correspondência do seletor), e e.target é o elemento realmente clicado (pode ser descendente do filho casado). Use e.delegateTarget para acessar o pai em handlers delegados.
// 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)
})Desvinculando handlers delegados
Namespacing (click.task) é a forma mais limpa de desvincular handlers específicos sem afetar outros. .off('click', 'li') remove handlers delegados que casam com aquele seletor. .off('click') remove os handlers de clique (diretos e delegados). .off() remove tudo — use com cuidado. Para remover um handler específico, passe a referência original da função. Para plugins, sempre namespace eventos (click.myplugin) para que usuários possam desvincular limparamente sem conhecer seus detalhes internos.
// 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 matchPegadinhas da delegação
Delimite a delegação ao ancestral estável mais próximo — não delegue tudo ao document/body (cada evento sobe e é checado contra o seletor, o que é lento). Evite seletores amplos demais ('div'). Cuidado com stopPropagation nos filhos: impede que handlers delegados em ancestrais disparem. Se um filho interrompe a propagação, o handler delegado do pai nunca roda. O trade-off: delegação é flexível, mas adiciona um leve overhead por evento (casamento de seletor) — geralmente desprezível, mas importa em páginas enormes.
// 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 targetBoas práticas
Dicas de desempenho
Dicas-chave de desempenho: (1) cacheie seleções; (2) delimite consultas a um container com .find(); (3) prefira seletores #id (usa getElementById internamente); (4) evite *; (5) delegue eventos; (6) agrupe atualizações de DOM via fragments — cada append dispara reflow, então monte um fragment e anexe uma vez; (7) desanexe antes de manipulação pesada (operações em elementos desanexados não disparam reflow). Para listas de 1000+ itens, concatenação de strings + .html() é o mais rápido, mas fragment é mais limpo.
// 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)Desempenho de inserção no DOM
A inserção no DOM é o maior gargalo de desempenho. Cada .append() dispara reflow (o navegador recalcula o layout). Para inserções em lote: (1) monte uma string HTML e defina com .html() (o mais rápido para conteúdo simples); (2) use um document fragment e anexe uma vez (mais limpo para elementos complexos); (3) desanexe o container, modifique, reanexe (evita reflow no DOM vivo durante a modificação). Para 1000+ itens, a abordagem de string é significativamente mais rápida que .append() por item.
// 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)Padrões jQuery modernos
Padrões do jQuery moderno (3.x): use .on()/.off() (funções legadas como .bind/.live/.delegate foram removidas ou descontinuadas). Use a interface de promise (.done/.fail) em vez dos callbacks success/error. Delimite o código em IIFEs ou ES modules — não polua globais. Pule $(document).ready se seu script está no fim do body. Prefira transições/animações CSS a .animate() (aceleradas por hardware, mais suaves). Use 'use strict'. Para projetos novos, avalie se um framework (Vue/React) é mais apropriado que 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)' })Acessibilidade
Essenciais de acessibilidade: adicione roles e estados ARIA (role='dialog', aria-modal, aria-expanded, aria-labelledby). Torne widgets personalizados acessíveis por teclado — trate Enter/Space para botões, setas para menus, Esc para fechar modals. Gerencie o foco: mova-o para dentro dos modals ao abrir, devolva-o ao gatilho ao fechar. Use elementos semânticos (<button>, <a>, <nav>) em vez de divs com onclick. Visibilidade: prefira ocultar via classes CSS (que leitores de tela podem ignorar) a display:none (que eles sempre ignoram).
// 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')Segurança: XSS e injeção de HTML
Nunca injete strings não confiáveis via .html() — executa tags <script> e handlers de evento embutidos (XSS). Use .text() para texto puro (escapado automaticamente). Quando precisar incluir HTML, sanitize primeiro (escapamento manual ou uma biblioteca como DOMPurify). O padrão mais seguro: construa elementos com $() e use .text() para conteúdo dinâmico — $('<li>').text(userInput) escapa automaticamente. Cuidado especial com padrões .append('<div>' + data + '</div>') — são vetores de XSS se data vier do usuário.
// 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, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''')
}
$('.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 inputPadrões comuns
Dialog modal
Um padrão de modal: crie overlay + modal, anexe ao body (foge de stacking contexts pais), fade in. Clique no overlay (não no modal) fecha — use e.target === this para detectar. Tecla Esc fecha. Sempre limpe (remova o DOM, desvincule handlers) ao fechar. Para produção, considere uma biblioteca (Magnific Popup, Bootstrap Modal) que trata acessibilidade (captura de foco, ARIA, devolução do foco ao gatilho), animações e modals de iframe/ajax. O padrão acima é a versão mínima feita à mão.
// 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>')
})Tabs
Padrão clássico de abas: clicar num link de aba ativa aquela aba. O href do link (#tab1) mapeia para o id do conteúdo. A classe active tanto no link quanto no conteúdo controla a visibilidade (CSS: .tab-content:not(.active) { display: none }). O handler usa delegação de eventos (trata abas adicionadas dinamicamente). preventDefault impede a hash da URL de mudar (ou omita preventDefault para habilitar deep-linking baseado em hash às abas). Por acessibilidade, adicione role='tab', aria-selected e navegação por setas do teclado.
<!-- 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>Accordion
Padrões de accordion: clicar num header alterna seu conteúdo. A variante de abertura única fecha os outros quando um abre (remova o bloco .not($h) para multi-abertura). Use aria-expanded para expor o estado a leitores de tela — o CSS pode estilizar com base nele (.acc-header[aria-expanded="true"] { ... }). slideToggle anima o conteúdo. Use <button> para os headers (acessível por teclado por padrão). Para muitos itens, a delegação de eventos no pai evita vincular cada header individualmente.
<!-- 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: detecte quando o usuário rola perto do fundo, busque mais itens, anexe-os. Proteja contra cargas concorrentes (flag loading). Quando o servidor não retorna mais itens, desvincule o handler de scroll (sem mais tentativas). Anexe via fragment por desempenho. Faça throttle do handler de scroll (dispara muitas vezes por segundo) — com debounce/_.throttle ou checando a flag loading (como aqui) para pular enquanto uma requisição está em andamento. Alternativa moderna: IntersectionObserver num elemento sentinela no fundo.
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()
}
})Busca ao vivo (com debounce)
Busca ao vivo: enquanto o usuário digita, consulte o servidor e mostre resultados. O debounce é essencial — sem ele, cada tecla dispara uma requisição (digitação rápida = dezenas de requisições). O debounce espera N ms após a última tecla antes de disparar. 300ms é um bom padrão. Sempre trate a query vazia (limpe resultados). Para produção, também cancele requisições em andamento quando uma nova começa (use .abort() no jqXHR anterior) para evitar respostas fora de ordem. Alternativas modernas: AbortController com fetch.
// 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)Snippets de jQuery relacionados
Copy-paste ready code for common tasks.
Selectors
Select elements by id, class, attribute, and pseudo-filters.
Events & Delegation
Bind handlers with on(), support delegation and namespaced removal.
DOM Manipulation
Get/set text, html, attributes, classes, and insert nodes.
AJAX Requests
Use $.ajax, $.get, $.post, and load with promises.
Effects & Animation
Show, hide, fade, slide, and animate elements.
Traversing the DOM
Navigate relatives and filter the matched set.
Utility Methods
Iterate, merge, and filter with jQuery helpers.
Method Chaining
Chain jQuery methods and use end() to restore context.
Was this helpful?