Primeiros passos
Instalação via CDN
O jQuery UI depende do núcleo do jQuery — sempre carregue o jQuery antes do jquery-ui.js. O CSS fornece a tematização padrão e é necessário para widgets como Datepicker e Dialog exibirem corretamente. A versão 1.13.x suporta jQuery 1.8+.
<!-- jQuery UI requires jQuery core first -->
<link rel="stylesheet"
href="https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css">
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>Instalação via npm
Instalar via npm permite tree-shaking importando apenas os widgets necessários (por exemplo, jquery-ui/ui/widgets/datepicker). Importar o bundle completo 'jquery-ui' inclui os widgets e efeitos. O tema CSS precisa ser importado separadamente.
# Install via npm
npm install jquery jquery-ui
# Import in your bundle
import $ from "jquery";
import "jquery-ui/ui/widgets/datepicker";
import "jquery-ui/themes/base/all.css";
// Or import the full bundle
import "jquery-ui";Inicialização básica de widget
Os widgets do jQuery UI seguem o mesmo padrão de plugin: $(selector).widgetName(options). Passe um objeto de opções para configurar, chame funções via a sintaxe de string ('methodName', args...). Sempre envolva a inicialização em $(function(){}) ou coloque o script no fim do body.
$(function () {
// Initialize a widget on a selector
$("#datepicker").datepicker();
$("#dialog").dialog();
// Pass options as an object
$("#accordion").accordion({
active: false,
collapsible: true,
});
// Get or set an option after init
$("#accordion").accordion("option", "active", 1);
});Padrão de função de widget
A API baseada em string é consistente entre os widgets. 'option' getter/setter, 'enable'/'disable', 'widget' (retorna o elemento mais externo) e 'destroy' (restaura a marcação original) são suportados por cada widget. Use destroy ao remover elementos para evitar vazamentos de memória.
// All widgets share the same API conventions
$("#dialog").dialog("open"); // call a method
$("#dialog").dialog("option", "title"); // get an option
$("#dialog").dialog("option", "modal", true); // set an option
$("#dialog").dialog("disable"); // disable widget
$("#dialog").dialog("enable"); // enable widget
$("#dialog").dialog("widget"); // get the wrapper element
$("#dialog").dialog("destroy"); // remove widget entirelyConfiguração de tema
O jQuery UI traz ~24 temas prontos. O tema 'base' é o padrão. O ThemeRoller (themroller.jqueryui.com) gera temas personalizados. Carregue seu próprio CSS depois do base para sobrescrever classes específicas como .ui-widget-header ou .ui-state-default.
<!-- Default base theme -->
<link rel="stylesheet"
href="https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css">
<!-- Other bundled themes: ui-lightness, ui-darkness, smoothness, redmond, ... -->
<link rel="stylesheet"
href="https://code.jquery.com/ui/1.13.2/themes/smoothness/jquery-ui.css">
<!-- Override theme with your own CSS -->
<link rel="stylesheet" href="jquery-ui.css">
<link rel="stylesheet" href="my-theme-overrides.css">Convenção de nomenclatura de classes
O framework CSS usa uma convenção de nomes consistente ui-*. Estados de interação (default, hover, active, focus) são aplicados automaticamente pelos widgets. Você pode usar essas classes diretamente na sua própria marcação para casar com a estilização do jQuery UI.
/* jQuery UI CSS classes are namespaced with ui- */
.ui-widget /* base widget class */
.ui-widget-header /* header bar (accordion, datepicker) */
.ui-widget-content /* content area */
.ui-state-default /* default interactive state */
.ui-state-hover /* mouse-over state */
.ui-state-active /* active/selected state */
.ui-state-focus /* keyboard focus state */
.ui-state-disabled /* disabled state */
.ui-corner-all /* rounded corners (themable) */
.ui-icon /* base icon class */Draggable
Draggable básico
Tornar um elemento arrastável é uma única chamada. O elemento pode então ser movido com o mouse. A classe ui-widget-content aplica a estilização padrão do tema. Draggable herda o posicionamento — relative/absolute é aplicado conforme necessário.
<!-- HTML -->
<div id="box" class="ui-widget-content" style="width:100px;height:100px;">
Drag me
</div>
<!-- JS -->
<script>
$(function () {
$("#box").draggable();
});
</script>Opções do Draggable
As opções controlam como o arrasto se comporta. 'axis' limita o movimento a um eixo, 'containment' restringe a região de arrasto, 'grid' encaixa em intervalos, e 'revert' devolve o elemento à posição inicial. 'helper: clone' arrasta uma cópia em vez do original.
$("#box").draggable({
axis: "x", // constrain to x or y axis
containment: "parent", // or "window", "document", or selector
cursor: "move", // cursor while dragging
cursorAt: { left: 5 }, // offset cursor from drag handle
grid: [20, 20], // snap to grid
delay: 100, // ms delay before drag starts
distance: 5, // px before drag starts
revert: true, // snap back to start
revertDuration: 200, // revert animation duration
scroll: false, // prevent auto-scroll
helper: "clone", // "original", "clone", or function
opacity: 0.6, // opacity while dragging
zIndex: 1000, // z-index while dragging
});Eventos de drag
Três eventos disparam durante um arrasto: 'start' (uma vez no início), 'drag' (continuamente enquanto move) e 'stop' (uma vez no fim). O objeto ui fornece position (relativo ao pai) e offset (relativo à página). Trabalho pesado no 'drag' pode prejudicar o desempenho.
$("#box").draggable({
start: function (event, ui) {
console.log("Drag started", ui.position);
},
drag: function (event, ui) {
// Fires continuously during drag
console.log(ui.position.left, ui.position.top);
},
stop: function (event, ui) {
console.log("Drag stopped at", ui.position);
console.log("Offset:", ui.offset);
},
});Handle e cancel
'handle' restringe o início do arrasto a um elemento filho específico — útil quando a caixa inteira deve ser móvel, mas só via uma barra de título. 'cancel' impede o arrasto a partir de certos elementos, como inputs ou textareas, em que a interação com o mouse é necessária para editar.
<!-- Only the header acts as the drag handle -->
<div id="box" class="ui-widget-content">
<div class="drag-handle">Drag from here</div>
<div class="content">Some content here</div>
<textarea>Editable content</textarea>
</div>
<script>
$("#box").draggable({
handle: ".drag-handle", // only this starts the drag
cancel: "textarea", // these elements never start a drag
});
</script>Restringindo o movimento
Containment restringe onde o elemento pode ser arrastado. 'parent', 'window', 'document', um seletor ou um array explícito [x1,y1,x2,y2] funcionam. Combinado com 'grid', você pode criar posicionamento preciso e encaixado para editores de layout ou dashboards.
// Constrain within a parent element
$("#box").draggable({ containment: "parent" });
// Constrain within the window
$("#box").draggable({ containment: "window" });
// Constrain within a specific selector
$("#box").draggable({ containment: "#drag-area" });
// Constrain to an explicit bounding box [x1, y1, x2, y2]
$("#box").draggable({ containment: [0, 0, 500, 300] });
// Snap to a 50px grid
$("#box").draggable({ grid: [50, 50] });Encaixe em elementos
'snap' faz o draggable saltar para se alinhar aos elementos alvo quando estiver perto o suficiente. 'snapMode' controla o alinhamento: 'inner' (dentro do alvo), 'outer' (fora do alvo) ou 'both'. Útil para construir ferramentas de diagramas ou layouts de dashboard em que os elementos devem se alinhar.
$(".card").draggable({
snap: ".snap-target", // selector of elements to snap to
snapMode: "inner", // "inner", "outer", or "both"
snapTolerance: 30, // px distance to trigger snap
});
// Snap to all siblings of the same class
$(".card").draggable({
snap: ".card",
snapTolerance: 20,
});Droppable
Droppable básico
Droppable define uma área alvo que aceita elementos arrastados. O callback 'drop' dispara quando um draggable é solto sobre ela. A propriedade ui.draggable dá uma referência ao elemento arrastado, para que você possa movê-lo ou processá-lo.
<div id="draggable" class="ui-widget-content">Drag me</div>
<div id="droppable" class="ui-widget-header">Drop here</div>
<script>
$(function () {
$("#draggable").draggable();
$("#droppable").droppable({
drop: function (event, ui) {
$(this).addClass("ui-state-highlight")
.html("Dropped!");
},
});
});
</script>Opções do Droppable
'accept' filtra quais draggables são permitidos — um seletor ou função. 'activeClass' e 'hoverClass' fornecem feedback visual. 'greedy: true' impede que droppables aninhados recebam ambos o evento de drop, útil para zonas de drop aninhadas.
$("#droppable").droppable({
accept: ".special", // only accept matching draggables
activeClass: "ui-state-default", // class while a drag is active
hoverClass: "ui-state-hover", // class while draggable is over
tolerance: "fit", // drop detection mode
greedy: true, // stop event propagation
disabled: false, // disable the droppable
});Eventos de drop
Cinco eventos cobrem o ciclo de vida completo do drop. 'activate'/'deactivate' disparam quando um arrasto correspondente começa/termina. 'over'/'out' disparam quando o draggable entra/sai da zona. 'drop' dispara apenas numa liberação bem-sucedida. Use-os para feedback visual progressivo.
$("#droppable").droppable({
activate: function (event, ui) {
// Fires when an accepted draggable starts moving
$(this).addClass("ui-state-default");
},
deactivate: function (event, ui) {
// Fires when the drag ends (drop or cancel)
$(this).removeClass("ui-state-default");
},
over: function (event, ui) {
// Draggable entered the drop zone
$(this).addClass("ui-state-hover");
},
out: function (event, ui) {
// Draggable left the drop zone
$(this).removeClass("ui-state-hover");
},
drop: function (event, ui) {
// Draggable was released here
console.log("Dropped:", ui.draggable);
},
});Seletor accept
'accept' pode ser uma string de seletor ou uma função que retorna booleano. A função recebe o elemento arrastado e roda para cada candidato, permitindo aplicar lógica de runtime como atributos de dados ou estados computados. Draggables não aceitos não disparam eventos de drop.
<!-- HTML: red and blue boxes -->
<div class="red draggable">Red</div>
<div class="blue draggable">Blue</div>
<div id="red-bin" class="bin">Red bin</div>
<div id="blue-bin" class="bin">Blue bin</div>
<script>
// Only accept elements matching the selector
$("#red-bin").droppable({ accept: ".red" });
$("#blue-bin").droppable({ accept: ".blue" });
// Or use a function for dynamic logic
$("#any-bin").droppable({
accept: function (drag) {
return $(drag).data("category") === "recyclable";
},
});
</script>Modos de tolerance
Tolerance define quanta sobreposição é exigida para um drop registrar. 'fit' é o mais estrito (elemento inteiro dentro). 'pointer' é baseado no cursor do mouse. 'intersect' (50% de sobreposição) é um bom equilíbrio para a maioria das UIs. 'touch' é o mais permissivo.
$("#droppable").droppable({
// "fit": draggable must be fully inside (default)
tolerance: "fit",
// "intersect": at least 50% overlap
tolerance: "intersect",
// "pointer": mouse pointer must be inside
tolerance: "pointer",
// "touch": any edge touching counts
tolerance: "touch",
});Feedback visual com classes
Combine activeClass (mostrada sempre que um arrasto aceito está em andamento) e hoverClass (mostrada quando o draggable está sobre a zona) para dar feedback claro aos usuários. No handler de drop, você normalmente anexa o draggable para re-paiá-lo na zona de drop.
<!-- CSS -->
<style>
.drop-active { border: 2px dashed #ccc; }
.drop-hover { border: 2px solid #0a0; background: #efe; }
</style>
<!-- JS -->
$("#zone").droppable({
accept: ".item",
activeClass: "drop-active",
hoverClass: "drop-hover",
drop: function (event, ui) {
$(this).append(ui.draggable);
ui.draggable.css({ top: 0, left: 0 });
},
});Resizable
Resizable básico
Resizable adiciona alças de redimensionamento a um elemento. Por padrão, uma alça aparece no canto inferior direito (se). O elemento precisa de posicionamento aplicado (relative/absolute) para as alças ancorarem corretamente.
<div id="box" class="ui-widget-content">
Resize me from the corner
</div>
<script>
$(function () {
$("#box").resizable();
});
</script>Alças de resize
'handles' controla quais arestas/cantos recebem alças de redimensionamento. Use direções de bússola: n, e, s, w, ne, se, sw, nw. O padrão é 'e, s, se'. Você pode fornecer elementos de alça personalizados por seletor para controle total de estilo.
$("#box").resizable({
handles: "n, e, s, w, ne, se, sw, nw", // all eight handles
});
// Or specify handle elements
$("#box").resizable({
handles: {
n: ".n-handle",
se: ".se-handle",
},
});Opções do Resizable
As opções restringem e personalizam o redimensionamento. 'aspectRatio' mantém as proporções (ótimo para imagens/vídeo). 'alsoResize' sincroniza outro elemento. 'ghost' mostra uma prévia esmaecida durante o resize, aplicando o tamanho real ao soltar. Dimensões min/max impõem limites.
$("#box").resizable({
alsoResize: "#other", // resize another element in sync
animate: true, // animate to final size
animateDuration: 200, // ms
aspectRatio: 16 / 9, // preserve width:height ratio
autoHide: true, // hide handles until hover
containment: "parent", // restrict resize within parent
grid: [10, 10], // snap to grid
maxHeight: 400,
maxWidth: 600,
minHeight: 100,
minWidth: 100,
ghost: true, // show a ghost outline while resizing
});Eventos de resize
Como draggable, resize dispara start/resize/stop. O objeto ui tem 'size' (width, height) e 'position' (left, top). Ao redimensionar pelas arestas norte ou oeste, tanto size quanto position mudam. Use o evento resize para atualizar UI dependente, como prévia ao vivo.
$("#box").resizable({
start: function (event, ui) {
console.log("Resize start", ui.size, ui.position);
},
resize: function (event, ui) {
// Fires continuously during resize
ui.size.width; // new width
ui.size.height; // new height
ui.position.left; // new position (may change for n/w handles)
},
stop: function (event, ui) {
console.log("Final size:", ui.size);
},
});Aspect ratio e restrições
Use aspectRatio (um número ou booleano true para travar a proporção atual) para imagens e mídia. Combinado com restrições min/max, você evita tamanhos estranhos. O encaixe em grid alinha a intervalos — útil para interfaces de editor e ferramentas de layout.
// Keep a 4:3 ratio
$("#photo").resizable({ aspectRatio: 4 / 3 });
// Keep ratio and stay within bounds
$("#photo").resizable({
aspectRatio: 4 / 3,
maxWidth: 800,
maxHeight: 600,
minWidth: 100,
minHeight: 75,
});
// Snap to a grid of 20px
$("#grid-box").resizable({ grid: [20, 20] });Modos animate e ghost
'animate' transiciona suavemente para o novo tamanho depois de o mouse ser solto. 'ghost' mostra uma prévia semitransparente durante o arrasto, aplicando a mudança real só na liberação. Juntos, criam uma experiência de resize polida e sem engasgos.
// Animate to the final size after release
$("#box").resizable({
animate: true,
animateDuration: "slow", // or ms number
animateEasing: "swing",
});
// Show a ghost outline while dragging, apply on release
$("#box").resizable({
ghost: true,
helper: "ui-resizable-helper", // class for the ghost
});
// Combine both
$("#box").resizable({ ghost: true, animate: true });Selectable
Selectable básico
Selectable transforma uma lista de filhos num grupo selecionável. Clique para selecionar, ou arraste um laço para selecionar vários. Segure Ctrl/Cmd para acrescentar à seleção, Shift para selecionar uma faixa. Itens selecionados recebem a classe ui-selected automaticamente.
<ol id="selectable">
<li class="ui-widget-content">Item 1</li>
<li class="ui-widget-content">Item 2</li>
<li class="ui-widget-content">Item 3</li>
</ol>
<script>
$(function () {
$("#selectable").selectable();
});
</script>Opções do Selectable
'filter' restringe quais filhos participam. 'tolerance' controla o comportamento do laço: 'touch' seleciona em qualquer sobreposição (padrão), 'fit' exige cercamento total. Defina 'autoRefresh: false' para listas grandes, melhorando o desempenho — chame $(...).selectable('refresh') manualmente após mudanças de layout.
$("#selectable").selectable({
filter: "li", // which children can be selected
tolerance: "touch", // "touch" or "fit" for lasso overlap
distance: 0, // px before lasso starts
delay: 0, // ms delay before lasso starts
autoRefresh: true, // recompute positions on each drag
disabled: false,
cancel: "a, .no-select", // elements that never start selection
});Eventos de select
Eventos disparam durante o ciclo de vida da seleção: 'selecting'/'unselecting' enquanto arrasta, 'selected'/'unselected' uma vez confirmado, e 'start'/'stop' para a operação geral. Cada objeto ui tem o elemento relevante (selecting, selected etc.).
$("#selectable").selectable({
selecting: function (event, ui) {
// ui.selecting: element being lassoed
$(ui.selecting).addClass("highlight");
},
selected: function (event, ui) {
// ui.selected: element just confirmed selected
console.log("Selected:", $(ui.selected).text());
},
unselecting: function (event, ui) {
$(ui.unselecting).removeClass("highlight");
},
unselected: function (event, ui) {
console.log("Unselected:", $(ui.unselected).text());
},
start: function (event, ui) { /* lasso started */ },
stop: function (event, ui) { /* lasso released */ },
});Filtrando itens
Use 'filter' para permitir que apenas filhos específicos sejam selecionados, e 'cancel' para excluir outros. Útil para galerias em que alguns itens (bloqueados, somente leitura) não devem participar. O laço simplesmente ignora elementos não correspondentes.
<ul id="gallery">
<li class="selectable-item">Photo 1</li>
<li class="locked">Locked</li>
<li class="selectable-item">Photo 2</li>
</ul>
<script>
$("#gallery").selectable({
filter: ".selectable-item", // only these can be selected
cancel: ".locked", // locked items never select
});
</script>Estilizando itens selecionados
O jQuery UI aplica as classes ui-selecting (durante o arrasto) e ui-selected (após soltar) automaticamente. Estilize-as para dar feedback. Leia a seleção atual a qualquer momento via $('.ui-selected') dentro do container — prático para toolbars e ações em lote.
/* CSS */
#selectable .ui-selecting {
background: #feca40; /* while dragging */
}
#selectable .ui-selected {
background: #f39814; /* confirmed selection */
color: white;
}
#selectable li {
margin: 3px; padding: 6px;
border: 1px solid #ccc;
}
/* selected count badge */
function updateCount() {
var n = $("#selectable .ui-selected").length;
$("#count").text(n + " selected");
}
$("#selectable").on("selectablestop", updateCount);Seleção programática
Chame 'refresh' depois de adicionar/remover itens para que o hit-testing do laço continue preciso. Não há função 'select' embutido, mas você pode alternar a classe ui-selected manualmente. Limpe removendo essa classe dos itens.
// Refresh positions after DOM changes
$("#selectable").selectable("refresh");
// Disable / enable
$("#selectable").selectable("disable");
$("#selectable").selectable("enable");
// Remove the widget
$("#selectable").selectable("destroy");
// Manually select an item (set the class)
$("#selectable li").eq(2).addClass("ui-selected");
// Clear all selections
$("#selectable .ui-selected").removeClass("ui-selected");Sortable
Sortable básico
Sortable torna os itens de lista reordenáveis por arrasto. Os itens se movem visualmente durante o arrasto e a ordem do DOM se atualiza ao soltar. Útil para listas de tarefas, galerias de fotos e qualquer conteúdo com ordem de prioridade.
<ul id="sortable">
<li class="ui-widget-content">Item 1</li>
<li class="ui-widget-content">Item 2</li>
<li class="ui-widget-content">Item 3</li>
</ul>
<script>
$(function () {
$("#sortable").sortable();
});
</script>Opções do Sortable
As opções refinam o comportamento de ordenação. 'placeholder' estiliza o espaço deixado; forcePlaceholderSize garante que ele corresponda às dimensões do item. 'axis' restringe a horizontal/vertical. 'handle' designa uma alça de arrasto — ideal quando o item inteiro tem filhos interativos.
$("#sortable").sortable({
axis: "y", // constrain to vertical
cursor: "move",
handle: ".handle", // drag from this element only
placeholder: "sortable-placeholder", // class for the drop preview
forcePlaceholderSize: true, // match placeholder to item size
helper: "clone", // "original" or "clone"
opacity: 0.7,
revert: true, // animate item into place
tolerance: "pointer", // "intersect" or "pointer"
scroll: true, // auto-scroll the page
containment: "parent", // restrict within parent
});Eventos de sort
Eventos-chave: 'start'/'stop' delimitam a ordenação. 'change' dispara quando a posição do item muda durante o arrasto. 'update' dispara apenas quando a ordem final difere da inicial — é aí que você persiste a nova ordem, frequentemente via toArray(), que retorna os IDs dos itens em ordem.
$("#sortable").sortable({
start: function (event, ui) {
ui.item; // the dragged element
ui.placeholder; // the placeholder element
ui.helper; // the helper being dragged
},
change: function (event, ui) {
// Position in list changed during drag
},
sort: function (event, ui) {
// Fires continuously while sorting
},
beforeStop: function (event, ui) {
// Just before the item is placed
},
stop: function (event, ui) {
console.log("Sort ended");
},
update: function (event, ui) {
// Order actually changed — persist it here
var order = $(this).sortable("toArray");
saveOrder(order);
},
});Listas conectadas
'connectWith' liga múltiplos sortables para que itens possam ser arrastados entre eles — ótimo para boards Kanban ou gerenciadores de pipeline. Cada lista ainda rastreia sua própria ordem via toArray(). Use os eventos receive/remove para reagir a transferências entre listas.
<ul id="list-a" class="connected">
<li>Task A1</li><li>Task A2</li>
</ul>
<ul id="list-b" class="connected">
<li>Task B1</li>
</ul>
<script>
$(".connected").sortable({
connectWith: ".connected", // allow moving between lists
placeholder: "ui-state-highlight",
}).disableSelection();
</script>Placeholder e helper
O placeholder é o espaço vazio mostrado onde o item vai cair — estilize-o para dar feedback claro de drop. forcePlaceholderSize é importante quando os itens têm alturas variadas. Uma função helper personalizada permite mostrar uma prévia simplificada durante o arrasto.
$("#sortable").sortable({
placeholder: "ui-state-highlight", // class for the gap
forcePlaceholderSize: true,
helper: function (event, el) {
// Return a custom helper element
return $("<div class='custom-helper'>Moving...</div>");
},
cursorAt: { top: 10, left: 10 },
});
// Use a clone as the helper instead of moving the original
$("#sortable").sortable({ helper: "clone" });Funções do sort
toArray() retorna os IDs na ordem atual — o mais útil para persistência. serialize() monta uma query string quando os IDs seguem a convenção 'name_number'. cancel() desfaz a ordenação mais recente. Chame refresh() depois de adicionar itens programaticamente.
// Get current order as an array of IDs
var order = $("#sortable").sortable("toArray");
// ["item-1", "item-3", "item-2"]
// Get option values
var placeholder = $("#sortable").sortable("option", "placeholder");
// Serialize items as a query string (uses id="name_number")
var data = $("#sortable").sortable("serialize");
// "item[]=1&item[]=2&item[]=3"
// Cancel the current sort (revert)
$("#sortable").sortable("cancel");
// Refresh positions after DOM changes
$("#sortable").sortable("refresh");
// Disable / enable / destroy
$("#sortable").sortable("disable");
$("#sortable").sortable("enable");
$("#sortable").sortable("destroy");Accordion
Accordion básico
O accordion espera pares de elementos cabeçalho + conteúdo (o cabeçalho deve vir primeiro). Por padrão, só uma seção fica aberta por vez. O elemento de cabeçalho padrão é h3, mas pode ser mudado via a opção header. Os painéis de conteúdo seguem cada cabeçalho.
<div id="accordion">
<h3>Section 1</h3>
<div>Content for section 1</div>
<h3>Section 2</h3>
<div>Content for section 2</div>
<h3>Section 3</h3>
<div>Content for section 3</div>
</div>
<script>
$(function () {
$("#accordion").accordion();
});
</script>Opções do Accordion
Defina 'collapsible: true' para permitir os painéis fechados (o padrão força um aberto). 'heightStyle: content' dimensiona cada painel pelo seu conteúdo; 'fill' torna os painéis da altura do container; 'auto' usa a altura do painel mais alto.
$("#accordion").accordion({
active: 0, // index of open panel (false = all closed)
collapsible: true, // allow closing all panels
disabled: false,
animate: 200, // ms or "ease name" or false
heightStyle: "content", // "auto", "fill", or "content"
header: "h3", // header selector
icons: {
header: "ui-icon-triangle-1-e",
activeHeader: "ui-icon-triangle-1-s",
},
event: "click", // event that toggles panels
});Eventos do Accordion
beforeActivate permite vetar uma mudança de painel retornando false — útil para avisos de mudanças não salvas. activate dispara após a animação completar. O objeto ui dá os elementos de cabeçalho e painel antigos/novos para ambos os eventos.
$("#accordion").accordion({
beforeActivate: function (event, ui) {
// ui.oldHeader, ui.oldPanel (closing)
// ui.newHeader, ui.newPanel (opening)
// Return false to cancel
if ($(ui.newHeader).data("locked")) return false;
},
activate: function (event, ui) {
// Fires after a panel finishes opening
console.log("Opened:", ui.newHeader.text());
},
create: function (event, ui) {
// Fires on initialization
console.log("Accordion created, open:", ui.header.text());
},
});Ícones personalizados
icons mapeia as classes de ícone fechado (header) e aberto (activeHeader). Passe false para desabilitar ícones. Você pode usar qualquer biblioteca de ícones (FontAwesome, Material Icons) fornecendo os nomes de classe apropriados — o span do ícone é criado automaticamente.
$("#accordion").accordion({
icons: {
header: "ui-icon-circle-arrow-e",
activeHeader: "ui-icon-circle-arrow-s",
},
});
// Disable icons entirely
$("#accordion").accordion({ icons: false });
// Use your own icon classes (e.g. with FontAwesome)
$("#accordion").accordion({
icons: {
header: "fa fa-plus",
activeHeader: "fa fa-minus",
},
});Collapsible e múltiplas seções
Para um accordion verdadeiro de 'múltiplos abertos ao mesmo tempo', o accordion do jQuery UI não suporta nativamente — em vez disso, inicialize accordions collapsible separados por seção, ou use tabs. A opção 'collapsible: true' só permite fechar o painel atualmente aberto.
// Allow all panels to be closed
$("#accordion").accordion({
collapsible: true,
active: false, // start with all closed
});
// Make every section independently toggleable
// (a true multi-open accordion = separate collapsibles)
$(".section").each(function () {
$(this).accordion({
collapsible: true,
active: false,
header: ".section-header",
});
});Accordion dinâmico
Chame refresh() depois de adicionar ou remover painéis para que o widget re-vincule. Use a opção active para abrir programaticamente um painel por índice. O padrão beforeActivate é uma forma limpa de carregar conteúdo do painel via AJAX só na primeira abertura.
// Refresh after adding content
$("#accordion").append("<h3>New</h3><div>Content</div>");
$("#accordion").accordion("refresh");
// Switch the open panel
$("#accordion").accordion("option", "active", 2);
// Disable / enable
$("#accordion").accordion("disable");
$("#accordion").accordion("enable");
// Destroy
$("#accordion").accordion("destroy");
// Load content on demand (AJAX-style)
$("#accordion").accordion({
beforeActivate: function (event, ui) {
var panel = ui.newPanel;
if (panel.is(":empty")) {
panel.load("/api/section/" + ui.newHeader.data("id"));
}
},
});Autocomplete
Autocomplete básico
Passe um array simples de strings a 'source' para sugestões estáticas. O widget filtra por substring conforme o usuário digita. As sugestões aparecem num dropdown; selecionar uma preenche o input. A lista também pode conter objetos {label, value} para exibição mais rica.
<label for="city">City:</label>
<input id="city" type="text">
<script>
$(function () {
var cities = ["London", "Paris", "Berlin", "Madrid", "Rome"];
$("#city").autocomplete({ source: cities });
});
</script>Fonte de dados remota
Quando source é uma URL, o autocomplete envia uma requisição GET com ?term= texto digitado e espera um array JSON. minLength adia a requisição até caracteres suficientes serem digitados, para reduzir a carga do servidor. A opção delay faz debounce da digitação rápida.
$("#city").autocomplete({
source: "/api/cities", // server endpoint
minLength: 2, // start suggesting after 2 chars
delay: 300, // ms between keystroke and request
});
// The server should return JSON like:
// ["London", "Paris", "Berlin"]
// or [{ "label": "London, UK", "value": "London" }]Opções do Autocomplete
autoFocus: true destaca a primeira sugestão, para que apertar Enter a selecione imediatamente. position configura o posicionamento do menu relativo ao input usando o Position do jQuery UI. appendTo é útil quando o input está num container absolutamente posicionado com problemas de overflow.
$("#city").autocomplete({
source: cities, // array, URL, or function
minLength: 1, // chars before suggestions appear
delay: 300, // ms between keystroke and request
autoFocus: true, // focus first item automatically
appendTo: "#container", // where to render the menu
position: { my: "left top", at: "left bottom" },
disabled: false,
});Função source personalizada
Uma source em função dá controle total — útil para cache, filtragem personalizada ou combinar múltiplos endpoints. Você DEVE chamar response(results) com um array, mesmo vazio. Cada item pode ter campos arbitrários além de label/value, acessíveis no handler de select.
$("#city").autocomplete({
source: function (request, response) {
// request.term is the typed text
// response() must be called with the results array
$.getJSON("/api/cities", { q: request.term })
.done(function (data) {
response(data);
})
.fail(function () {
response([]); // always call response, even on error
});
},
select: function (event, ui) {
// ui.item.label, ui.item.value
$("#city-id").val(ui.item.id);
},
});Eventos do Autocomplete
focus dispara enquanto o usuário percorre as sugestões (teclado ou hover). select dispara quando um item é escolhido. change dispara ao perder o foco e é o lugar certo para validar que o valor final existe na fonte. Retornar false impede o comportamento padrão de preencher o input.
$("#city").autocomplete({
source: cities,
focus: function (event, ui) {
// Fires when an item is highlighted (not selected)
$("#preview").text(ui.item.label);
return false; // prevent setting the input value on focus
},
select: function (event, ui) {
// Fires when an item is chosen
$("#city").val(ui.item.label);
$("#city-id").val(ui.item.value);
return false; // prevent default behavior
},
change: function (event, ui) {
// Fires when input loses focus
if (!ui.item) {
// User typed something not in the list
console.log("No match:", this.value);
}
},
});Categorias e renderização personalizada
Sobrescreva _renderMenu ou _renderItem para personalizar o layout do dropdown. Este exemplo agrupa as sugestões por categoria, com linhas de cabeçalho. O padrão $.widget estende o autocomplete base, então todas as opções e eventos originais continuam funcionando. Comum em interfaces de busca.
$.widget("custom.catcomplete", $.ui.autocomplete, {
_renderMenu: function (ul, items) {
var that = this, currentCategory = "";
$.each(items, function (index, item) {
if (item.category !== currentCategory) {
ul.append("<li class='ui-autocomplete-category'>"
+ item.category + "</li>");
currentCategory = item.category;
}
that._renderItemData(ul, item);
});
},
});
// Use the new widget
$("#search").catcomplete({
source: [
{ label: "Java", category: "Languages" },
{ label: "JavaScript", category: "Languages" },
{ label: "React", category: "Frameworks" },
],
});Datepicker
Datepicker básico
Clicar ou focar o input abre um popup de calendário. A data selecionada preenche o input como texto. O calendário mostra o mês atual com setas de navegação para o mês anterior/seguinte. Por padrão, as datas usam o formato dos EUA (mm/dd/yy).
<label for="date">Pick a date:</label>
<input type="text" id="date">
<script>
$(function () {
$("#date").datepicker();
});
</script>Opções do Datepicker
minDate/maxDate aceitam um objeto Date, um número (dias de hoje) ou uma string ('+1M +1W'). numberOfMonths exibe múltiplos meses — útil para seletores de intervalo de datas. changeMonth/changeYear adicionam dropdowns para saltar a anos distantes.
$("#date").datepicker({
dateFormat: "yy-mm-dd", // ISO format
defaultDate: "+1", // tomorrow when calendar opens
minDate: 0, // no past dates (today+)
maxDate: "+1Y", // up to one year ahead
numberOfMonths: 2, // show 2 months side by side
showButtonPanel: true, // Today/Done buttons
changeMonth: true, // dropdown for month
changeYear: true, // dropdown for year
showAnim: "fadeIn", // open animation
duration: "fast",
firstDay: 1, // start week on Monday
showWeek: true, // show week numbers
});Formato de data
A opção dateFormat usa tokens estilo PHP. 'yy' significa ano de quatro dígitos (o y extra é intencional). Use a função formatDate() para converter um Date em string com os mesmos tokens, e parseDate() para o inverso.
$("#date").datepicker({
dateFormat: "yy-mm-dd", // 2026-07-04
});
// Format tokens:
// d - day of month, no leading zero (1)
// dd - day, two digits (01)
// D - short day name (Mon)
// DD - full day name (Monday)
// m - month, no leading zero (1)
// mm - month, two digits (01)
// M - short month name (Jan)
// MM - full month name (January)
// y - two-digit year (26)
// yy - four-digit year (2026)
// @ - Unix timestamp
// ! - Windows ticks
// Common formats:
// "mm/dd/yy" -> 07/04/2026
// "yy-mm-dd" -> 2026-07-04
// "DD, MM d, yy" -> Friday, July 4, 2026Datas min/max e intervalos
Para um seletor de intervalo de datas, ligue dois datepickers: quando o início é escolhido, defina o minDate do fim; quando o fim é escolhido, defina o maxDate do início. beforeShowDay permite desabilitar ou estilizar dias individuais — noWeekends é um embutido que bloqueia sábados e domingos.
// Restrict to a date range
$("#start").datepicker({
minDate: 0,
maxDate: "+6M",
onSelect: function (dateText) {
// Set the end date's minimum to the start date
$("#end").datepicker("option", "minDate", dateText);
},
});
$("#end").datepicker({
minDate: 0,
maxDate: "+6M",
onSelect: function (dateText) {
$("#start").datepicker("option", "maxDate", dateText);
},
});
// Disable weekends
$("#date").datepicker({
beforeShowDay: $.datepicker.noWeekends,
});Localização
O jQuery UI traz arquivos regionais na pasta i18n para ~40 locales. Carregue o arquivo e aplique com $.datepicker.regional['fr']. Você também pode sobrescrever strings individuais inline. O arquivo regional define nomes de meses, nomes de dias, firstDay e dateFormat de uma vez.
// Set the regionalization
$("#date").datepicker($.datepicker.regional["fr"]);
// Override specific strings
$("#date").datepicker({
monthNames: ["janvier","février","mars","avril","mai","juin",
"juillet","août","septembre","octobre","novembre","décembre"],
dayNamesMin: ["Di","Lu","Ma","Me","Je","Ve","Sa"],
firstDay: 1,
dateFormat: "dd/mm/yy",
prevText: "Précédent",
nextText: "Suivant",
closeText: "Fermer",
currentText: "Aujourd'hui",
});
// Include the regional file for built-in locales:
// <script src="jquery-ui/i18n/datepicker-fr.js"></script>Datepicker inline e eventos
Aplique o datepicker a uma div em vez de um input para um calendário inline sempre visível — ótimo para interfaces de reserva. onSelect dispara quando uma data é escolhida, onChangeMonthYear ao navegar entre meses. getDate/setDate funcionam com objetos Date para controle programático.
<!-- Inline (always visible) calendar -->
<div id="inline-calendar"></div>
<script>
$("#inline-calendar").datepicker({
onSelect: function (dateText, inst) {
console.log("Selected:", dateText);
},
onChangeMonthYear: function (year, month, inst) {
console.log("Viewing:", month + "/" + year);
},
beforeShow: function (input, inst) {
// Fires before the popup opens
return { /* override options */ };
},
onClose: function (dateText, inst) {
// Fires when the popup closes
},
});
// Methods
$("#date").datepicker("setDate", "+7"); // set to a week from today
$("#date").datepicker("getDate"); // returns a Date object
$("#date").datepicker("option", "minDate", new Date(2026, 0, 1));
</script>Dialog
Dialog básico
O atributo title do elemento vira a barra de título do dialog. O dialog abre automaticamente por padrão e é arrastável/redimensionável. O elemento é movido para um wrapper do jQuery UI com empilhamento de z-index adequado. Feche via o botão X ou pressionando Escape.
<div id="dialog" title="Basic dialog">
<p>This is a simple dialog window.</p>
</div>
<script>
$(function () {
$("#dialog").dialog();
});
</script>Opções do Dialog
Defina autoOpen: false para criar o dialog oculto, e depois chame dialog('open') quando necessário — esse é o padrão padrão para dialogs sob demanda. modal adiciona uma sobreposição que bloqueia a interação com a página. position usa o utilitário Position do jQuery UI para posicionamento preciso.
$("#dialog").dialog({
autoOpen: false, // don't open on init
modal: true, // dim the page behind
width: 400,
height: "auto",
minWidth: 200,
maxWidth: 600,
resizable: true,
draggable: true,
closeOnEscape: true,
position: { my: "center", at: "center", of: window },
title: "Custom Title", // override the title attr
show: { effect: "fade", duration: 200 },
hide: { effect: "fade", duration: 200 },
});Botões do dialog
buttons aceita um array (preferido, permite ícones e opções por botão) ou um objeto (texto: handler). Dentro de um handler, 'this' é o elemento do dialog — chame $(this).dialog('close') para dispensar. Os botões são tematizados automaticamente e alinhados à direita por padrão.
$("#dialog").dialog({
buttons: [
{
text: "Save",
icon: "ui-icon-disk",
click: function () {
saveForm();
$(this).dialog("close");
},
},
{
text: "Cancel",
click: function () {
$(this).dialog("close");
},
},
],
});
// Shortcut object form (1.12+)
$("#dialog").dialog({
buttons: {
"Save": function () { saveForm(); $(this).dialog("close"); },
"Cancel": function () { $(this).dialog("close"); },
},
});Eventos do dialog
beforeClose é o guardião — retorne false para manter o dialog aberto (útil para avisos de mudanças não salvas). close dispara depois de o dialog ser dispensado, o lugar certo para reiniciar o estado do formulário ou liberar recursos. Os eventos drag/resize espelham os das interações subjacentes.
$("#dialog").dialog({
beforeClose: function (event, ui) {
// Return false to prevent closing
if (!confirm("Discard changes?")) return false;
},
open: function (event, ui) {
console.log("Dialog opened");
},
close: function (event, ui) {
console.log("Dialog closed");
// Clean up form state
$(this).find("form")[0].reset();
},
focus: function (event, ui) {
// Dialog gained focus
},
dragStart: function (event, ui) { /* dragging started */ },
dragStop: function (event, ui) { /* dragging ended */ },
resizeStart: function (event, ui) { /* resizing started */ },
resizeStop: function (event, ui) { /* resizing ended */ },
});Dialog modal e de confirmação
Crie um dialog a partir de um elemento montado dinamicamente para confirmações pontuais. A sobreposição modal impede a interação com o resto da página. Sempre destrua e remova o elemento no handler de close para evitar vazar nós DOM quando o dialog for dispensado.
function confirmDialog(message, onConfirm) {
$("<div>" + message + "</div>").dialog({
modal: true,
title: "Confirm",
buttons: {
"OK": function () {
onConfirm();
$(this).dialog("close");
},
"Cancel": function () {
$(this).dialog("close");
},
},
close: function () {
$(this).dialog("destroy").remove(); // clean up
},
});
}
// Usage
confirmDialog("Delete this item?", function () {
deleteItem();
});Conteúdo AJAX e funções
Use o evento open para carregar conteúdo via AJAX e inicializar quaisquer widgets aninhados. Sempre limpe o conteúdo ao fechar, para que a próxima abertura seja nova. moveToTop eleva o dialog acima dos outros no z-index — útil para dialogs empilhados. isOpen é um getter booleano para lógica condicional.
// Load content from a URL when opening
function openEditDialog(id) {
var $dlg = $("#edit-dialog");
$dlg.dialog({
autoOpen: false,
modal: true,
open: function () {
$dlg.load("/api/edit/" + id, function () {
// Initialize widgets in loaded content
$dlg.find(".datepicker").datepicker();
});
},
close: function () {
$dlg.empty(); // clear for next open
},
});
$dlg.dialog("open");
}
// Common methods
$("#dialog").dialog("open");
$("#dialog").dialog("close");
$("#dialog").dialog("isOpen"); // returns boolean
$("#dialog").dialog("moveToTop"); // bring to front
$("#dialog").dialog("option", "title", "New Title");Progressbar
Progressbar básica
A progressbar mostra uma barra horizontal preenchida até uma porcentagem (0-100). A opção value define o progresso atual. A barra se tematiza automaticamente com a estilização do jQuery UI. A largura do container determina a largura total da barra — defina via CSS.
<div id="progress"></div>
<script>
$(function () {
$("#progress").progressbar({ value: 37 });
});
</script>Modo indeterminado
Definir value como false coloca a barra em modo indeterminado — uma listra animada indica que 'algo está acontecendo', sem porcentagem específica. Use quando o total é desconhecido (por exemplo, aguardando um servidor). Volte a um número assim que puder rastrear o progresso.
<div id="progress"></div>
<script>
// Set value to false for an indeterminate (animated) bar
$("#progress").progressbar({ value: false });
// Switch to determinate later when you know the percent
$("#progress").progressbar("option", "value", 50);
</script>Opções da progressbar
A opção 'max' permite usar escalas diferentes de 100 (por exemplo, max: 1000 para um download em KB). O valor é interpretado como fração de max. A opção classes (1.12+) permite adicionar classes personalizadas a elementos internos específicos para tematização fina.
$("#progress").progressbar({
value: 0, // 0-100, or false for indeterminate
max: 100, // upper bound (default 100)
disabled: false,
// 1.12+ supports a 'classes' option for theming
classes: {
"ui-progressbar": "highlight",
"ui-progressbar-value": "animated",
},
});Atualizando o valor
Atualize a barra definindo a opção value. Um loop setInterval simula progresso para uploads ou tarefas longas. Para uploads reais, use o evento de progresso de upload do XHR para atualizar value com base nos bytes transferidos. Sempre limpe o timer ao terminar.
// Simulate a file upload
var progress = 0;
$("#progress").progressbar({ value: 0 });
var timer = setInterval(function () {
progress += 5;
$("#progress").progressbar("option", "value", progress);
if (progress >= 100) {
clearInterval(timer);
console.log("Complete!");
}
}, 200);
// Get current value
var current = $("#progress").progressbar("option", "value");Evento change e rótulos personalizados
change dispara sempre que o valor se atualiza, complete dispara a 100% — ambos úteis para estilização ou rótulos dinâmicos. Para mostrar o texto da porcentagem, adicione um rótulo absolutamente posicionado sobre a barra. Atualize-o dentro do handler de change para mantê-lo em sincronia.
$("#progress").progressbar({
value: 0,
change: function () {
var v = $("#progress").progressbar("value");
$("#progress .ui-progressbar-value")
.css("background", v < 50 ? "#fa0" : "#0a0");
},
complete: function () {
$("#progress .ui-progressbar-value").css("background", "#0a0");
$("#progress-label").text("Done!");
},
});
// Overlay a text label
$("#progress").append(
'<div id="progress-label" style="position:absolute;left:50%;top:0;">Loading...</div>'
);Slider
Slider básico
Slider cria uma alça arrastável numa trilha horizontal. A faixa padrão é 0-100, com a alça começando em 0. A trilha é totalmente tematizada. Defina dimensões via CSS no container — width para sliders horizontais, height para verticais.
<div id="slider"></div>
<script>
$(function () {
$("#slider").slider();
});
</script>Opções do slider
Use 'values' (array) em vez de 'value' para um slider de faixa com duas alças. 'range: true' sombreia a área entre as alças; 'range: min' sombreia da alça ao mínimo; 'range: max' sombreia da alça ao máximo. 'step' deve dividir (max - min) exatamente.
$("#slider").slider({
min: 0,
max: 100,
step: 1, // increment size
value: 50, // single value
values: [25, 75], // two-handle range (omit 'value')
orientation: "horizontal", // or "vertical"
range: true, // or "min", "max"
disabled: false,
animate: "fast", // or ms, or false
});Eventos do slider
slide dispara continuamente durante o arrasto — ideal para atualizar um rótulo ao vivo. Retornar false dentro de slide cancela o movimento, útil para restringir valores dinamicamente. change dispara após soltar e em mudanças de opções programáticas; use-o para persistir o valor.
$("#slider").slider({
start: function (event, ui) {
// User started dragging a handle
console.log("Start:", ui.value || ui.values);
},
slide: function (event, ui) {
// Fires continuously during drag
// Return false to prevent the handle from moving
$("#label").text(ui.value);
},
change: function (event, ui) {
// Fires after the handle is released (and on programmatic change)
saveValue(ui.value);
},
stop: function (event, ui) {
// User released the handle
},
});Slider de faixa
Um slider de faixa com duas alças é construído definindo range: true e fornecendo um array values. ui.values[0] é a alça inferior, ui.values[1] a superior. As alças não podem cruzar. Esse é o padrão clássico para filtros de preço ou intervalo de datas.
<div id="range-slider"></div>
<p>Price: $<span id="min-price"></span> - $<span id="max-price"></span></p>
<script>
$("#range-slider").slider({
range: true,
min: 0,
max: 500,
values: [75, 300],
slide: function (event, ui) {
$("#min-price").text(ui.values[0]);
$("#max-price").text(ui.values[1]);
},
});
</script>Vertical e orientações
Sliders verticais precisam de uma altura explícita definida via CSS — width se aplica ao eixo transversal. A alça se move para cima/baixo em vez de esquerda/direita. O sombreamento da faixa funciona da mesma forma. Útil para mesas de som, equalizadores ou qualquer UI em que a orientação vertical seja mais natural.
// Vertical slider
$("#vertical").slider({
orientation: "vertical",
min: 0,
max: 100,
value: 60,
});
// Vertical range
$("#vertical-range").slider({
orientation: "vertical",
range: true,
min: 0,
max: 100,
values: [20, 80],
});
/* CSS: vertical sliders need a height */
/* #vertical { height: 200px; } */
</script>Funções do slider
Para sliders de faixa, use values() (sem argumentos) para obter um array, values(index, value) para definir uma alça, ou values(array) para definir ambas. Definir opções como min/max/step em runtime reposiciona automaticamente as alças dentro dos novos limites.
// Get or set the value
$("#slider").slider("value");
$("#slider").slider("value", 75);
// Get or set both handles of a range slider
var vals = $("#slider").slider("values"); // [25, 75]
$("#slider").slider("values", 0, 30); // set lower handle
$("#slider").slider("values", [30, 90]); // set both
// Get or set options
$("#slider").slider("option", "max", 200);
$("#slider").slider("option", "disabled", true);
// Disable / enable / destroy
$("#slider").slider("disable");
$("#slider").slider("enable");
$("#slider").slider("destroy");Spinner
Spinner básico
Spinner adiciona botões para cima/baixo a um input de texto para entrada numérica. Os usuários podem digitar diretamente, clicar nos botões ou usar as setas do teclado. Manter um botão pressionado acelera o incremento. O valor do input é interpretado como número a cada mudança.
<label for="qty">Quantity:</label>
<input id="qty" type="text" value="1">
<script>
$(function () {
$("#qty").spinner();
});
</script>Opções do spinner
min/max impõem limites — os botões não passam deles. step controla o tamanho do incremento (use decimais como 0.1 para controle fino). numberFormat com culture habilita formatação localizada (por exemplo, 'C' com 'ja-JP' mostra ienes). O Globalize.js precisa estar carregado para suporte a culture.
$("#qty").spinner({
min: 0, // minimum value
max: 100, // maximum value
step: 1, // increment size
page: 10, // page up/down increment
numberFormat: "n", // "n" for number, "C" for currency
culture: "en-US", // locale for formatting
disabled: false,
incremental: true, // accelerate while holding
icons: {
up: "ui-icon-triangle-1-n",
down: "ui-icon-triangle-1-s",
},
});Formatação numérica e culture
Com o Globalize.js carregado, o spinner formata os valores conforme a culture especificada — símbolos de moeda, separadores decimais e agrupamento se localizam. numberFormat 'C' é moeda, 'n' é número com contagem opcional de decimais (n2 = 2 decimais). Útil para formulários internacionalizados.
<!-- Requires Globalize.js for culture support -->
<script src="globalize.js"></script>
<script src="globalize.culture.ja-JP.js"></script>
<script>
// Currency spinner (Japanese yen)
$("#price").spinner({
numberFormat: "C",
culture: "ja-JP",
step: 100,
min: 0,
});
// Decimal spinner
$("#weight").spinner({
step: 0.01,
numberFormat: "n2", // 2 decimal places
min: 0,
});
</script>Eventos do spinner
spin dispara a cada incremento/decremento (clique no botão ou tecla de seta). Retornar false cancela a mudança — ideal para validação personalizada. change dispara ao perder o foco; ui.value é null se o input não interpretar como número válido, o lugar para mostrar erros de validação.
$("#qty").spinner({
spin: function (event, ui) {
// Fires when a button is clicked or arrow pressed
// ui.value is the new value
// Return false to cancel the change
if (ui.value > 10) {
alert("Max 10 per order");
return false;
}
},
change: function (event, ui) {
// Fires when the value changes and input loses focus
// ui.value may be null if invalid
if (ui.value === null) {
alert("Please enter a valid number");
}
},
start: function (event, ui) { /* spin started */ },
stop: function (event, ui) { /* spin stopped */ },
});Step personalizado e funções
stepUp/stepDown/pageUp/pageDown simulam pressionamentos de botão programaticamente. value() sem argumento é um getter; com um argumento é um setter que passa pela validação. Handlers de spin personalizados permitem construir spinners não numéricos, como horas, cores ou unidades personalizadas.
// Time spinner (steps of 15 minutes)
$("#time").spinner({
step: 15,
min: 0,
max: 1439, // 24 * 60 - 1
numberFormat: "n0",
spin: function (event, ui) {
// Wrap around at midnight
if (ui.value > 1439) return false; // or wrap: $(this).spinner("value", 0);
},
});
// Methods
$("#qty").spinner("value"); // get current value
$("#qty").spinner("value", 5); // set value
$("#qty").spinner("stepUp"); // increment by one step
$("#qty").spinner("stepDown"); // decrement by one step
$("#qty").spinner("pageUp"); // increment by 'page' steps
$("#qty").spinner("pageDown");
$("#qty").spinner("disable");
$("#qty").spinner("enable");
$("#qty").spinner("destroy");Validação e parse personalizado
Sobrescreva _parse e _format para construir spinners para valores não decimais — cores hex, horas, ângulos ou qualquer unidade personalizada. _parse converte o texto do input num número; _format converte de volta para exibição. Essa é a forma mais limpa de estender o spinner para entradas específicas de domínio.
// Custom spinner for hexadecimal colors
$.widget("custom.hexspinner", $.ui.spinner, {
_parse: function (value) {
// String -> number
return parseInt(value, 16);
},
_format: function (value) {
// number -> string
return value.toString(16).toUpperCase().padStart(6, "0");
},
});
$("#color").hexspinner({
min: 0x000000,
max: 0xffffff,
step: 0x10,
});
// Prevent invalid input
$("#qty").on("keydown", function (e) {
if (e.key === "-" && $(this).spinner("option", "min") >= 0) {
e.preventDefault();
}
});Tabs
Tabs básicas
Tabs espera uma ul de links apontando para IDs de painéis de conteúdo, seguida dos próprios painéis. Os hrefs dos links (#tab-1) conectam abas aos painéis. A primeira aba é ativa por padrão. As tabs são navegáveis por teclado (setas, Home, End) e compatíveis com ARIA.
<div id="tabs">
<ul>
<li><a href="#tab-1">First</a></li>
<li><a href="#tab-2">Second</a></li>
<li><a href="#tab-3">Third</a></li>
</ul>
<div id="tab-1">Content 1</div>
<div id="tab-2">Content 2</div>
<div id="tab-3">Content 3</div>
</div>
<script>
$(function () {
$("#tabs").tabs();
});
</script>Opções das tabs
active define a aba inicialmente aberta por índice (ou false para começar colapsado). heightStyle 'fill' torna os painéis da altura do container; 'content' dimensiona cada um pelo seu próprio conteúdo (padrão). 'event: mouseover' cria tabs ativadas por hover.
$("#tabs").tabs({
active: 0, // index of active tab (false = all hidden)
collapsible: false, // allow closing the active tab
disabled: [], // array of disabled indices
event: "click", // event to switch tabs ("mouseover" etc.)
heightStyle: "content", // "auto", "fill", or "content"
show: { effect: "fadeIn", duration: 200 },
hide: { effect: "fadeOut", duration: 200 },
});Eventos das tabs
beforeActivate é o guardião — retorne false para bloquear a troca (por exemplo, aviso de mudanças não salvas). activate dispara após a troca completar. beforeLoad/load servem para tabs AJAX — beforeLoad permite personalizar ou cancelar a requisição; load dispara em sucesso.
$("#tabs").tabs({
beforeActivate: function (event, ui) {
// ui.newTab, ui.newPanel (opening)
// ui.oldTab, ui.oldPanel (closing)
// Return false to cancel the switch
if ($(ui.newPanel).find("form").hasUnsavedChanges()) {
return confirm("Discard changes?");
}
},
activate: function (event, ui) {
// Fires after the new tab is shown
console.log("Now on:", ui.newTab.text());
},
beforeLoad: function (event, ui) {
// For AJAX tabs — fires before loading remote content
ui.jqXHR.error(function () {
ui.panel.text("Failed to load content.");
});
},
load: function (event, ui) {
// AJAX content finished loading
},
});Tabs AJAX
Quando o href de uma aba é uma URL (não uma âncora), as tabs carregam o conteúdo via AJAX na ativação. A resposta substitui o painel. beforeLoad permite mostrar um spinner, configurar a requisição AJAX ou cancelá-la. O conteúdo carregado fica em cache para a sessão por padrão na 1.12+.
<div id="tabs">
<ul>
<li><a href="#local">Local</a></li>
<li><a href="remote.html">Remote (AJAX)</a></li>
<li><a href="api/data.json">API Data</a></li>
</ul>
<div id="local">This content is in the page.</div>
<!-- Remote panels are created automatically -->
</div>
<script>
$("#tabs").tabs({
beforeLoad: function (event, ui) {
// Show a loading indicator
ui.panel.html("Loading...");
// Cache the loaded content
ui.ajaxSettings.cache = true;
},
});
</script>Tabs collapsible e sortable
Com collapsible: true, clicar na aba ativa a fecha (nenhuma aba permanece aberta). Parear tabs com sortable na nav permite aos usuários reordenar abas arrastando. Depois de adicionar ou remover abas/painéis, chame refresh() para que o widget re-vincule a nova estrutura.
// Allow collapsing the active tab
$("#tabs").tabs({ collapsible: true });
// Make tabs reorderable by drag
$("#tabs").tabs().find(".ui-tabs-nav").sortable({
axis: "x",
stop: function () {
$("#tabs").tabs("refresh");
},
});
// Dynamically add a new tab
function addTab(id, label, content) {
var nav = $("#tabs .ui-tabs-nav");
nav.append('<li><a href="#' + id + '">' + label + '</a></li>');
$("#tabs").append('<div id="' + id + '">' + content + '</div>');
$("#tabs").tabs("refresh");
}Funções das tabs
disable/enable aceitam um índice ou array de índices. A opção active é tanto getter quanto setter da aba atual — use-a para trocar programaticamente. load() recarrega o conteúdo AJAX de uma aba. refresh() é essencial depois de adicionar, remover ou reordenar abas.
// Disable / enable specific tabs
$("#tabs").tabs("disable", 1); // disable second tab
$("#tabs").tabs("enable", 1);
$("#tabs").tabs("option", "disabled", [0, 2]); // disable multiple
// Switch to a tab by index
$("#tabs").tabs("option", "active", 2);
// Reload an AJAX tab
$("#tabs").tabs("load", 1);
// Refresh after structural changes
$("#tabs").tabs("refresh");
// Get the active tab index
var active = $("#tabs").tabs("option", "active");
// Destroy
$("#tabs").tabs("destroy");Tooltip
Tooltip básico
Chamar tooltip() no document substitui os tooltips nativos de title por versões tematizadas do jQuery UI. O conteúdo do atributo title vira o texto do tooltip. Os tooltips aparecem no hover e desaparecem no mouseout, com animação de fade suave por padrão.
<label for="age">Age:</label>
<input id="age" title="Please enter your age in years">
<script>
$(function () {
$(document).tooltip();
});
</script>Opções do tooltip
Sobrescreva 'content' como função para gerar HTML de tooltip dinâmico (por exemplo, a partir de atributos data ou AJAX). 'items' é um seletor que controla quais elementos disparam tooltips. 'track: true' faz o tooltip seguir o cursor — útil para textos de ajuda detalhados em diagramas.
$(document).tooltip({
content: function () {
// Default: returns the element's title attribute
return $(this).attr("title");
},
items: "[title]", // which elements get tooltips
position: { my: "left top+15", at: "left bottom" },
show: { effect: "fadeIn", duration: 200 },
hide: { effect: "fadeOut", duration: 200 },
tooltipClass: "custom-tooltip", // class for the tooltip div
track: false, // follow the mouse cursor
disabled: false,
close: null, // (event defaults handle this)
});Conteúdo personalizado
A função content permite construir tooltips ricos com HTML, imagens ou conteúdo buscado via AJAX. Retorne uma string (HTML permitido). tooltipClass adiciona uma classe personalizada para estilizar. É o padrão padrão para prévias de miniaturas ou balões de ajuda em campos de formulário.
<!-- HTML with data attributes -->
<a href="#" class="help" data-help="Click to save your changes">Save</a>
<a href="#" class="help" data-help="Undo the last action">Undo</a>
<script>
$(".help").tooltip({
content: function () {
return "<strong>Help:</strong> " + $(this).data("help");
},
tooltipClass: "help-tooltip",
});
</script>
<!-- With an image preview -->
$(".thumb").tooltip({
content: function () {
var src = $(this).attr("href");
return "<img src='" + src + "' width='200'>";
},
});Eventos do tooltip
open e close disparam conforme os tooltips aparecem e desaparecem. A propriedade ui.tooltip dá o elemento do tooltip para personalização. Um padrão comum é manter o tooltip aberto enquanto o usuário passa o mouse sobre ele — útil quando o tooltip contém conteúdo interativo como links.
$(".help").tooltip({
open: function (event, ui) {
// Tooltip just appeared
ui.tooltip; // the tooltip element
},
close: function (event, ui) {
// Tooltip just disappeared
ui.tooltip.one("transitionend", function () {
// Cleanup after the hide animation
});
},
create: function (event, ui) {
// Widget initialized
},
});
// Prevent tooltip from closing on hover
$(".help").tooltip({
close: function (event, ui) {
ui.tooltip.hover(
function () { $(this).stop(true).fadeIn(); },
function () { $(this).fadeOut(); }
);
},
});Position e funções
Position usa o utilitário Position do jQuery UI: 'my' é a âncora do tooltip, 'at' é a âncora do alvo. collision trata casos extremos — 'flip' move para o outro lado se transbordaria. open()/close() mostram/ocultam tooltips programaticamente, úteis para erros de validação.
$("#target").tooltip({
position: {
my: "center top", // tooltip's anchor point
at: "center bottom", // target's anchor point
of: "#target", // optional: position relative to this
collision: "flip", // "flip", "fit", "flipfit", "none"
using: function (pos, feedback) {
$(this).css(pos);
console.log(feedback.horizontal, feedback.vertical);
},
},
});
// Methods
$("#target").tooltip("open"); // show programmatically
$("#target").tooltip("close"); // hide programmatically
$("#target").tooltip("disable");
$("#target").tooltip("enable");
$("#target").tooltip("widget"); // get the tooltip div
$("#target").tooltip("destroy");Tooltips de validação de formulário
Tooltips são uma forma limpa de mostrar erros de validação inline. Guarde a mensagem de erro num atributo data, defina content para lê-lo, e chame open() para exibir. Retornar false no handler de open impede o tooltip quando não há erro. Estilize com tooltipClass para uma estilização de erro em vermelho.
<!-- Show validation errors as tooltips -->
<form id="form">
<input id="email" type="text" placeholder="Email">
<input id="submit" type="submit" value="Submit">
</form>
<script>
$("#form").tooltip({
items: "input",
content: function () {
return $(this).data("error") || "";
},
position: { my: "left top", at: "left bottom+5" },
tooltipClass: "error-tooltip",
open: function (event, ui) {
var el = $(event.originalEvent.target);
if (!el.data("error")) return false; // don't show if no error
},
});
$("#submit").on("click", function (e) {
var email = $("#email").val();
if (!email.includes("@")) {
e.preventDefault();
$("#email").data("error", "Please enter a valid email")
.tooltip("open");
}
});
</script>Efeitos
Efeitos do núcleo
O jQuery UI estende o show/hide/toggle do jQuery com efeitos nomeados e adiciona a função .effect() para animações que não ocultam. Cada um aceita um objeto de opções, uma duração e um callback. 'transfer' cria um contorno de elemento de transferência — útil para animações de arrastar-ao-carrinho.
// Built-in effects (beyond jQuery's show/hide/toggle)
$("#box").hide("fade", {}, 1000); // fade out
$("#box").show("slide", {}, 500); // slide in
$("#box").toggle("explode", {}, 800); // explode toggle
$("#box").effect("bounce", { times: 3 }, 300);
// Available effect names:
// blind, bounce, clip, drop, explode, fade, fold,
// highlight, puff, pulsate, scale, shake, size, slide, transferFunções de easing
O núcleo de efeitos do jQuery UI adiciona ~30 funções de easing de Robert Penner além do 'swing' e 'linear' padrão do jQuery. Use-as em qualquer chamada .animate(), na opção easing de show/hide/toggle, ou como terceiro argumento. 'easeOutBounce' e 'easeOutElastic' são populares para UIs divertidas.
// jQuery core provides: swing (default), linear
// jQuery UI adds ~30 more easing functions
$("#box").animate({ width: 500 }, 1000, "easeInOutBounce");
// Available easings (subset):
// easeInQuad, easeOutQuad, easeInOutQuad
// easeInCubic, easeOutCubic, easeInOutCubic
// easeInQuart, easeOutQuart, easeInOutQuart
// easeInExpo, easeOutExpo, easeInOutExpo
// easeInBack, easeOutBack, easeInOutBack
// easeInBounce, easeOutBounce, easeInOutBounce
// easeInElastic, easeOutElastic, easeInOutElasticShow/hide/toggle com efeitos
Passe um nome de efeito como primeiro argumento a show/hide/toggle para animar. O segundo argumento é um objeto de opções (direction, distance, percent etc., dependendo do efeito). O terceiro é a duração; o quarto, um callback. Efeitos em elementos ocultos ainda funcionam via show().
// show with an effect
$("#box").show("drop", { direction: "left" }, 500);
// hide with an effect
$("#box").hide("puff", {}, 500);
// toggle with an effect
$("#box").toggle("scale", { percent: 0 }, 500);
// With a callback
$("#box").hide("blind", 500, function () {
console.log("Animation complete");
});
// Direction option (where applicable)
$("#box").hide("slide", { direction: "up" });Animação de cor
O núcleo do jQuery não consegue animar cores — o núcleo de efeitos do jQuery UI adiciona isso. backgroundColor, color e borderColor tornam-se animáveis. switchClass e toggleClass aceitam uma duração para transicionar entre classes suavemente, interpolando todas as propriedades CSS alteradas.
// jQuery UI extends animate() to support colors
$("#box").animate({
backgroundColor: "#ff0000",
color: "#ffffff",
borderColor: "#000000",
}, 1000);
// Animate through the theme states
$("#box").animate(
{ backgroundColor: $.Color("#0a0") },
{ duration: 500 }
);
// Toggle class with smooth transitions
$("#box").switchClass("old-class", "new-class", 500);
$("#box").toggleClass("active", 500); // duration = animatedTransições de classe
addClass, removeClass e toggleClass ganham um argumento opcional de duração do jQuery UI — todas as propriedades CSS que diferem entre os estados animam suavemente. switchClass transiciona explicitamente entre duas classes. Essa é a forma mais limpa de animar entre estados tematizados.
// Add/remove classes with animation
$("#box").addClass("highlight", 500); // animate to new class
$("#box").removeClass("highlight", 500);
$("#box").toggleClass("highlight", 500);
// switchClass: smoothly transition from one class to another
$("#box").switchClass("state-default", "state-active", 500);
// All accept a callback
$("#box").addClass("expanded", 500, function () {
console.log("Done expanding");
});Referência de funções de efeito
.effect() aplica um efeito nomeado sem mudar a visibilidade (shake, bounce, pulsate são efeitos puros). .transfer() anima um contorno de caixa de um elemento a outro — clássico para o feedback 'adicionar ao carrinho'. Arrays de easing por propriedade permitem que propriedades diferentes usem easings diferentes.
// .effect() — run an effect without hiding
$("#box").effect("shake", { times: 3 }, 300);
// .transfer() — animate a transfer outline to another element
$("#product").effect("transfer", { to: "#cart" }, 500);
// .animate() with colors and easing
$("#box").animate({ left: 200, opacity: 0.5 }, "slow", "easeOutBounce");
// Custom animation with step
$("#box").animate({
width: ["toggle", "swing"], // [value, easing] per property
height: ["toggle", "linear"],
}, 1000);ThemeRoller
Básico do ThemeRoller
ThemeRoller é a aplicação web oficial para construir temas personalizados do jQuery UI. Ajuste cores, fontes, raio dos cantos e texturas com prévia ao vivo, e depois baixe um ZIP com o CSS tematizado e os sprites de imagem. Temas prontos (smoothness, ui-lightness etc.) também estão disponíveis no CDN.
<!-- Use a prebuilt theme from the CDN -->
<link rel="stylesheet"
href="https://code.jquery.com/ui/1.13.2/themes/smoothness/jquery-ui.css">
<!-- Or a custom theme from ThemeRoller (jqueryui.com/themeroller) -->
<!-- 1. Visit the ThemeRoller app -->
<!-- 2. Customize colors, fonts, corner radius, etc. -->
<!-- 3. Download the generated CSS file -->
<link rel="stylesheet" href="my-custom-theme/jquery-ui.css">Classes do framework CSS
O framework CSS é independente dos widgets JavaScript — use ui-widget, ui-widget-header, ui-widget-content e as classes de estado (ui-state-default, ui-state-hover, ui-state-active) na sua própria marcação para casar com a estilização do jQuery UI, sem qualquer inicialização de widget.
<!-- The jQuery UI CSS framework is reusable for custom markup -->
<div class="ui-widget">
<div class="ui-widget-header ui-corner-top">
<h3>Panel Header</h3>
</div>
<div class="ui-widget-content ui-corner-bottom">
<p>Panel content with themed styling.</p>
<button class="ui-button ui-widget ui-state-default ui-corner-all">
<span class="ui-icon ui-icon-gear"></span> Action
</button>
</div>
</div>Variáveis e estrutura de tema
Cada tema define o mesmo conjunto de classes, com cores e texturas diferentes. ui-state-highlight (amarelo) serve para avisos; ui-state-error (vermelho) para erros. As classes de canto (ui-corner-all, ui-corner-top etc.) tornam o border-radius tematizável — o ThemeRoller os define de uma vez.
/* ThemeRoller generates CSS with these key classes */
.ui-widget {
font-family: Arial, sans-serif; /* font family */
font-size: 1em; /* base font size */
}
.ui-widget-content { border: 1px solid #aaa; background: #fff; color: #222; }
.ui-widget-header { border: 1px solid #aaa; background: #ccc; color: #222; }
.ui-state-default { border: 1px solid #d3d3d3; background: #e6e6e6; }
.ui-state-hover { border: 1px solid #999; background: #dadada; }
.ui-state-active { border: 1px solid #aaa; background: #fff; }
.ui-state-focus { border: 1px solid #999; background: #dadada; }
.ui-state-highlight { border: 1px solid #fcefa1; background: #fbf9ee; }
.ui-state-error { border: 1px solid #cd0a0a; background: #fef1ec; }
.ui-corner-all { border-radius: 4px; } /* themable radius */Sobrescrita de tema personalizado
Carregue um tema base e depois sobrescreva com CSS de especificidade maior. Isso é mais rápido que rodar o ThemeRoller de novo para pequenos ajustes. Mire nas classes do framework (ui-widget-header, ui-state-default etc.) para reestilizar os widgets de uma vez. Remova o raio dos cantos para um visual plano e moderno.
/* Load the base theme first */
@import url("https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css");
/* Override specific elements */
.ui-widget-header {
background: linear-gradient(to bottom, #2c3e50, #34495e);
color: #ecf0f1;
}
.ui-state-default {
background: #3498db;
border-color: #2980b9;
color: #fff;
}
.ui-state-hover { background: #2980b9; }
.ui-state-active { background: #1abc9c; border-color: #16a085; }
.ui-corner-all { border-radius: 0; } /* sharper look */Troca de tema em runtime
Para trocar temas em runtime, carregue múltiplos arquivos CSS de tema e alterne a propriedade 'disabled' deles — só o habilitado se aplica. Persista a escolha no localStorage. Os widgets capturam a nova estilização imediatamente. Para uma solução de CSS único, troque o atributo href em vez disso.
<!-- Two theme stylesheets; toggle the disabled attribute -->
<link id="theme-light" rel="stylesheet"
href="themes/ui-lightness/jquery-ui.css">
<link id="theme-dark" rel="stylesheet"
href="themes/ui-darkness/jquery-ui.css" disabled>
<script>
function switchTheme(name) {
$("#theme-light").prop("disabled", name !== "light");
$("#theme-dark").prop("disabled", name !== "dark");
localStorage.setItem("theme", name);
}
// Restore on load
$(function () {
var saved = localStorage.getItem("theme") || "light";
switchTheme(saved);
});
</script>Tematizando widgets específicos
Mire nas classes específicas de widget (ui-datepicker, ui-dialog, ui-accordion-header) para reestilizar widgets individuais sem afetar os demais. A opção 'classes' da 1.12+ é mais limpa — adiciona classes personalizadas a elementos internos específicos, que você estiliza no seu CSS. Prefira-a a overrides globais quando possível.
/* Datepicker: style the calendar popup */
.ui-datepicker {
box-shadow: 0 4px 12px rgba(0,0,0,0.2);
border-radius: 0;
}
.ui-datepicker .ui-state-highlight { /* today */ background: #ffd; }
.ui-datepicker .ui-state-active { /* selected */ background: #2c3e50; }
/* Dialog: remove the default rounded corners */
.ui-dialog { border-radius: 0; box-shadow: 0 8px 30px rgba(0,0,0,0.3); }
/* Accordion: modernize the headers */
.ui-accordion .ui-accordion-header {
background: #f5f5f5;
border: none;
border-bottom: 1px solid #ddd;
font-weight: bold;
}
/* Use the 'classes' option (1.12+) for per-widget theming */
$("#dialog").dialog({
classes: { "ui-dialog": "my-dialog", "ui-dialog-titlebar": "my-title" },
});Snippets de jQuery UI relacionados
Copy-paste ready code for common tasks.
Draggable
Make elements draggable with axis, containment, and event callbacks.
Droppable
Create drop targets that accept draggable elements with hover and drop events.
Resizable
Add resize handles with min/max constraints and aspect ratio lock.
Sortable
Reorder list items via drag-and-drop and persist the new order.
Accordion
Collapsible content panels with only one section expanded at a time.
Datepicker
Calendar widget with date range limits, formatting, and inline mode.
Dialog
Modal window with buttons, animations, and dynamic open/close.
Tabs
Tabbed content panels with AJAX loading and event-driven switching.
Was this helpful?