Skip to content

jQuery UI Folha de referência

Conjunto selecionado de interações e widgets de interface construídos sobre o jQuery.

01

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
<!-- 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.

jquery-ui
# 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.

jquery-ui
$(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.

jquery-ui
// 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 entirely

Configuraçã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.

jquery-ui
<!-- 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
/* 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 */
02

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.

jquery-ui
<!-- 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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
<!-- 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.

jquery-ui
// 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.

jquery-ui
$(".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,
});
03

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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
<!-- 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.

jquery-ui
$("#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.

jquery-ui
<!-- 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 });
  },
});
04

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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
// 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.

jquery-ui
// 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 });
05

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.

jquery-ui
<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.

jquery-ui
$("#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.).

jquery-ui
$("#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.

jquery-ui
<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.

jquery-ui
/* 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.

jquery-ui
// 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");
06

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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
// 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");
07

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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
// 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.

jquery-ui
// 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"));
    }
  },
});
08

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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
$.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" },
  ],
});
09

Button

Button básico

O widget button tematiza qualquer elemento clicável (button, input[type=submit], a) com a estilização do jQuery UI. Adiciona a classe ui-button e gerencia os estados hover/active/focus. Âncoras viram botões estilizados, útil para navegação que deve parecer botões.

jquery-ui
<!-- Apply to button, input, or anchor elements -->
<button id="btn">Click me</button>
<input type="submit" id="submit" value="Submit">
<a href="#" id="link" class="btn">Link button</a>

<script>
  $(function () {
    $("#btn").button();
    $("#submit").button();
    $("#link").button();
  });
</script>

Opções do Button

Combine 'icon' e 'showLabel' para criar botões só de ícone (toolbars compactas). 'iconPosition' controla se o ícone precede ou segue o texto. Use 'label' para definir o texto programaticamente, útil quando ele muda em runtime (por exemplo, toggle Iniciar/Parar).

jquery-ui
$("#btn").button({
  disabled: false,
  text: true,              // show the label text
  icon: "ui-icon-gear",    // primary icon class
  iconPosition: "beginning", // "beginning" or "end"
  showLabel: true,         // text or icon only
  label: "Save",           // override the button's text
});

// Icon-only button (must set showLabel: false)
$("#icon-btn").button({
  icon: "ui-icon-disk",
  showLabel: false,
});

Buttonset (grupos de radio/checkbox)

buttonset agrupa radio buttons ou checkboxes numa única toolbar visualmente conectada. No jQuery UI 1.12+, buttonset foi descontinuado em favor de controlgroup(), que é mais flexível e funciona com qualquer tipo de input. Cada input precisa de um label correspondente.

jquery-ui
<div id="size-set">
  <input type="radio" id="s1" name="size"><label for="s1">S</label>
  <input type="radio" id="s2" name="size" checked><label for="s2">M</label>
  <input type="radio" id="s3" name="size"><label for="s3">L</label>
</div>

<script>
  $("#size-set").buttonset();

  // For checkboxes (multi-select):
  // $("#check-set").controlgroup();  // 1.12+
</script>

Ícones

O jQuery UI traz um sprite de ~170 ícones com prefixo ui-icon-. Comuns: ui-icon-gear, ui-icon-trash, ui-icon-search, ui-icon-close. Navegue pelo conjunto completo em api.jqueryui.com/theming/icons. Alterne ícones em runtime via a função option para toggles estilo play/pause.

jquery-ui
// Primary icon
$("#save").button({ icon: "ui-icon-disk" });

// Icon only (no text)
$("#play").button({
  icon: "ui-icon-play",
  showLabel: false,
});

// Change icon at runtime
$("#play").button("option", "icon", "ui-icon-pause");

// Available icons include:
// ui-icon-gear, ui-icon-disk, ui-icon-trash,
// ui-icon-search, ui-icon-close, ui-icon-check,
// ui-icon-arrowthick-1-n/e/s/w, and many more

Split button (toolbar)

O jQuery UI não tem um split button nativo — combine um botão regular com um botão só de ícone e um Menu oculto para construir um. O botão de seta alterna o menu. Esse padrão é comum em toolbars ricas como clientes de e-mail ou editores de documentos.

jquery-ui
<div class="toolbar">
  <button id="save">Save</button>
  <button id="save-arrow"><span class="ui-icon ui-icon-triangle-1-s"></span></button>
</div>

<script>
  $("#save").button();
  $("#save-arrow").button({ text: false, icon: "ui-icon-triangle-1-s" });

  $("#save-arrow").on("click", function () {
    $("#menu").menu("widget").show();
  });
</script>

<!-- Combine with a Menu for a true split button -->
<ul id="menu" style="display:none;">
  <li><div>Save</div></li>
  <li><div>Save As...</div></li>
  <li><div>Export</div></li>
</ul>

Funções do button

Use a função option para mudar label, ícone ou estado disabled em runtime — típico de botões com estado como 'Enviar' → 'Carregando...'. A função refresh relê o estado do elemento (útil para checkboxes alternados programaticamente). destroy remove toda a estilização.

jquery-ui
// Disable / enable
$("#btn").button("disable");
$("#btn").button("enable");

// Change options
$("#btn").button("option", "label", "Loading...");
$("#btn").button("option", "disabled", true);

// Get the button element
$("#btn").button("widget");

// Refresh after DOM changes (e.g. removing a class)
$("#btn").button("refresh");

// Remove the widget
$("#btn").button("destroy");
10

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).

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
$("#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, 2026

Datas 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.

jquery-ui
// 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.

jquery-ui
// 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.

jquery-ui
<!-- 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>
11

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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
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.

jquery-ui
// 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");
13

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.

jquery-ui
<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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
// 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.

jquery-ui
$("#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>'
);
14

Selectmenu

Selectmenu básico

Selectmenu substitui o dropdown select nativo por uma versão tematizada do jQuery UI. Suporta os recursos nativos (selected, opções disabled) e adiciona ícones, renderização personalizada e estilização consistente entre navegadores. O select subjacente permanece em sincronia, então os formulários enviam normalmente.

jquery-ui
<label for="speed">Speed:</label>
<select id="speed">
  <option>Slower</option>
  <option>Slow</option>
  <option selected="selected">Medium</option>
  <option>Fast</option>
  <option>Faster</option>
</select>

<script>
  $(function () {
    $("#speed").selectmenu();
  });
</script>

Opções do selectmenu

Defina width como null para usar a largura CSS do elemento, ou um número para pixels explícitos. A largura padrão se dimensiona automaticamente pela opção mais longa. position controla o posicionamento do menu relativo ao botão. appendTo é útil para selectmenus dentro de dialogs ou iframes.

jquery-ui
$("#speed").selectmenu({
  disabled: false,
  width: null,            // null = CSS width, number = px
  icons: { button: "ui-icon-triangle-1-s" },
  appendTo: null,         // where to render the menu
  position: { my: "left top", at: "left bottom" },
});

Eventos do selectmenu

change é o evento principal — dispara quando o usuário escolhe uma opção diferente. ui.item.value é o atributo value da opção, ui.item.label é seu texto. select dispara pouco antes de change e pode ser cancelado retornando false — útil para validação.

jquery-ui
$("#speed").selectmenu({
  change: function (event, ui) {
    // ui.item has the selected option's data
    console.log("Selected:", ui.item.value);
    console.log("Label:", ui.item.label);
  },
  focus: function (event, ui) {
    // Item highlighted in the dropdown
  },
  open: function (event, ui) {
    // Dropdown just opened
  },
  close: function (event, ui) {
    // Dropdown just closed
  },
  select: function (event, ui) {
    // Fires before change; return false to cancel
  },
});

Renderização personalizada

Sobrescreva _renderItem para adicionar ícones, descrições ou HTML personalizado a cada opção. item.element dá acesso ao <option> original, para que você possa ler atributos data. Essa é a forma padrão de construir dropdowns ricos, como seletores de projeto com ícones de status.

jquery-ui
$("#projects").selectmenu({
  // Render each item in the dropdown
  format: function (item) {
    // (deprecated in 1.12 — use _renderItem instead)
  },
});

// 1.12+ custom rendering via widget extension
$.widget("custom.iconselectmenu", $.ui.selectmenu, {
  _renderItem: function (ul, item) {
    var li = $("<li>"), wrapper = $("<div>", { text: item.label });
    if (item.disabled) li.addClass("ui-state-disabled");
    $("<span>", { class: "ui-icon " + item.element.data("icon") })
      .appendTo(wrapper);
    return li.append(wrapper).appendTo(ul);
  },
});

$("#projects").iconselectmenu();

Funções

Para definir o valor, use o .val() nativo no select e depois chame refresh() para atualizar a exibição do widget. Sempre chame refresh() depois de adicionar, remover ou mudar opções no select subjacente, para que o widget reflita o novo estado.

jquery-ui
// Open / close programmatically
$("#speed").selectmenu("open");
$("#speed").selectmenu("close");

// Get or set the value
var val = $("#speed").selectmenu("option", "value");  // not standard
$("#speed").val("fast").selectmenu("refresh");  // use .val() + refresh

// Refresh after modifying the underlying select
$("#speed").append("<option>New</option>");
$("#speed").selectmenu("refresh");

// Disable / enable
$("#speed").selectmenu("disable");
$("#speed").selectmenu("enable");

// Get the button or menu element
$("#speed").selectmenu("widget");    // the button wrapper
$("#speed").selectmenu("menuWidget"); // the menu ul

// Destroy
$("#speed").selectmenu("destroy");

Optgroups e opções desabilitadas

Selectmenu respeita elementos <optgroup> nativos — renderizam como cabeçalhos de grupo não selecionáveis, com tematização adequada. O atributo disabled em opções individuais também é honrado, exibindo-as esmaecidas e impedindo seleção. Os formulários ainda enviam o valor selecionado.

jquery-ui
<select id="category">
  <optgroup label="Frontend">
    <option value="react">React</option>
    <option value="vue">Vue</option>
  </optgroup>
  <optgroup label="Backend">
    <option value="node">Node.js</option>
    <option value="django" disabled>Django (deprecated)</option>
  </optgroup>
</select>

<script>
  $("#category").selectmenu({
    width: 200,
    change: function (event, ui) {
      console.log("Picked:", ui.item.value);
    },
  });
</script>
15

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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
$("#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.

jquery-ui
<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.

jquery-ui
// 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.

jquery-ui
// 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");
16

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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
<!-- 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.

jquery-ui
$("#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.

jquery-ui
// 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.

jquery-ui
// 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();
  }
});
17

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.

jquery-ui
<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.

jquery-ui
$("#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.

jquery-ui
$("#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+.

jquery-ui
<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.

jquery-ui
// 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.

jquery-ui
// 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");
18

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.

jquery-ui
<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.

jquery-ui
$(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.

jquery-ui
<!-- 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.

jquery-ui
$(".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.

jquery-ui
$("#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.

jquery-ui
<!-- 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>
19

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.

jquery-ui
// 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, transfer

Funçõ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-ui
// 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, easeInOutElastic

Show/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().

jquery-ui
// 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
// 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 = animated

Transiçõ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.

jquery-ui
// 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.

jquery-ui
// .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);
20

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.

jquery-ui
<!-- 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.

jquery-ui
<!-- 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.

jquery-ui
/* 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.

jquery-ui
/* 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.

jquery-ui
<!-- 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.

jquery-ui
/* 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" },
});

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.