Skip to content

jQuery Mobile Hoja de referencia

Framework de UI HTML5 optimizado para táctil en apps web móviles.

01

Primeros pasos

Estructura de la página

jQuery Mobile usa atributos data-role para mejorar el HTML. Una página es un div con data-role=page que contiene secciones de header, main y footer. La etiqueta meta viewport es esencial para un escalado correcto en dispositivos móviles. Carga el núcleo de jQuery antes que jquery.mobile.js.

jquery-mobile
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="https://code.jquery.com/jquery-1.11.1.min.js"></script>
  <script src="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
  <div data-role="page" id="home">
    <div data-role="header"><h1>Home</h1></div>
    <div data-role="main" class="ui-content">Content</div>
    <div data-role="footer"><h4>Footer</h4></div>
  </div>
</body>
</html>

Varias páginas en un documento

Puedes colocar varios divs data-role=page en un único archivo HTML. Enlázalos entre sí con hrefs de anclas (#about). jQuery Mobile muestra una página a la vez y anima las transiciones. Solo la primera página en orden del código se muestra en la carga inicial.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="header"><h1>Home</h1></div>
  <div data-role="main" class="ui-content">
    <a href="#about" class="ui-btn">Go to About</a>
  </div>
</div>

<div data-role="page" id="about" data-theme="b">
  <div data-role="header"><h1>About</h1></div>
  <div data-role="main" class="ui-content">
    <a href="#home" class="ui-btn" data-direction="reverse">Back</a>
  </div>
</div>

Navegación AJAX y enlaces

Por defecto, los enlaces a páginas internas (#id) y del mismo origen se obtienen vía AJAX y se intercambian con una transición. Usa data-ajax=false para forzar una carga de página completa normal (útil para páginas que no son de jQuery Mobile). data-prefetch precarga el objetivo para que la transición sea instantánea.

jquery-mobile
<!-- Default: links load via AJAX and animate a transition -->
<a href="detail.html" class="ui-btn">Open detail (AJAX)</a>

<!-- Force a full page reload (no AJAX) -->
<a href="external.html" data-ajax="false">Full reload</a>

<!-- Open in new window/tab -->
<a href="https://example.com" rel="external">External site</a>

<!-- Prefetch a page when this page loads -->
<a href="next.html" data-prefetch="true" class="ui-btn">Prefetch next</a>

Precarga y caché del DOM

La precarga carga en segundo plano las páginas enlazadas para que la navegación se sienta instantánea. Por defecto las páginas visitadas se eliminan del DOM, pero domCache las conserva para una navegación hacia atrás más rápida a costa de memoria. Actívalo por página con data-dom-cache o globalmente vía la opción del prototipo de page.

jquery-mobile
<!-- Prefetch several pages -->
<a href="page1.html" data-prefetch="true">Page 1</a>
<a href="page2.html" data-prefetch="true">Page 2</a>

<!-- Globally enable DOM caching of visited pages -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.page.prototype.options.domCache = true;
});
</script>

<!-- Cache a single page -->
<div data-role="page" id="cached" data-dom-cache="true">...</div>

Páginas de diálogo

Añade data-rel=dialog a un enlace (o data-dialog=true en la página) para abrir una página estilizada como diálogo modal con botón de cierre y transición. Usa data-rel=back en un enlace para cerrarla y volver a la página anterior.

jquery-mobile
<!-- Open a page as a dialog -->
<a href="#dialog" class="ui-btn" data-rel="dialog">Open dialog</a>

<div data-role="page" id="dialog" data-dialog="true">
  <div data-role="header"><h1>Dialog</h1></div>
  <div data-role="main" class="ui-content">
    <p>This page is styled as a dialog.</p>
    <a href="#" class="ui-btn" data-rel="back">Close</a>
  </div>
</div>

Configuración global (mobileinit)

El evento mobileinit se dispara tras cargar el núcleo de jQuery pero antes de que jQuery Mobile se inicialice — vincula tu configuración aquí, antes de incluir jquery.mobile.js. Anulaciones comunes: transiciones por defecto, ajustes AJAX y texto del mensaje de carga. Fjar autoInitializePage=false te permite controlar cuándo se inicializa la primera página.

jquery-mobile
<script src="jquery-1.11.1.min.js"></script>
<script>
// Bind BEFORE loading jquery.mobile.js
$(document).on("mobileinit", function () {
  $.mobile.defaultPageTransition = "slide";
  $.mobile.defaultDialogTransition = "pop";
  $.mobile.loadingMessage = "Loading...";
  $.mobile.ajaxEnabled = true;
  $.mobile.linkBindingEnabled = true;
  $.mobile.autoInitializePage = true;
});
</script>
<script src="jquery.mobile-1.4.5.min.js"></script>
02

Transiciones de página

Transiciones básicas

Añade data-transition a un enlace para elegir la animación al navegar. Las transiciones se basan en CSS (aceleradas por hardware cuando es posible). 'none' se salta la animación para una navegación instantánea. El mismo atributo funciona para diálogos y popups.

jquery-mobile
<!-- Apply a transition to a link -->
<a href="#page2" data-transition="slide">Slide</a>
<a href="#page2" data-transition="fade">Fade</a>
<a href="#page2" data-transition="pop">Pop</a>
<a href="#page2" data-transition="flip">Flip</a>
<a href="#page2" data-transition="none">None (instant)</a>

Tipos de transición

jQuery Mobile incluye un conjunto de transiciones CSS 2D/3D. Las 3D (turn, flow, flip) lucen geniales en dispositivos capaces pero se degradan con elegancia en hardware antiguo. pop y fade son las más eficientes y se recomiendan para diálogos y popups.

jquery-mobile
<!-- Available transitions in jQuery Mobile 1.4 -->
fade      <!-- default, fade in/out -->
pop       <!-- scale in from center (good for dialogs) -->
slide     <!-- slide left to right -->
slideup   <!-- slide up from bottom -->
slidedown <!-- slide down from top -->
slidfade  <!-- slide + fade -->
turn      <!-- 3D turn -->
flow      <!-- 3D flow -->
flip      <!-- 3D flip -->
none      <!-- no animation -->

Dirección e inverso

data-direction=reverse reproduce la transición hacia atrás — se usa típicamente en los botones de atrás para que la animación refleje la navegación hacia adelante. Esto se combina con data-transition; si no hay transición fijada, se invierte la predeterminada.

jquery-mobile
<!-- Reverse a transition (e.g., for Back buttons) -->
<a href="#home" data-transition="slide" data-direction="reverse">Back</a>

<!-- Globally reverse the default -->
<a href="#home" data-direction="reverse">Back (uses default transition reversed)</a>

Transiciones de diálogo

Los diálogos pueden usar cualquier transición, pero pop y slidedown se sienten más naturales para modales. Fija un valor por defecto global con $.mobile.defaultDialogTransition durante mobileinit. La acción de cierre del diálogo invierte la transición automáticamente.

jquery-mobile
<!-- Combine data-rel=dialog with a transition -->
<a href="#settings" data-rel="dialog" data-transition="pop">Settings</a>
<a href="#settings" data-rel="dialog" data-transition="slidedown">Settings (slide down)</a>

<!-- Set a global default dialog transition -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.defaultDialogTransition = "pop";
});
</script>

Desactivación y respaldo

Fija data-transition=none o el valor por defecto global en 'none' para desactivar las animaciones — útil en dispositivos de gama baja o por accesibilidad. jQuery Mobile detecta automáticamente el soporte de transformaciones 3D y degrada las transiciones 3D (flip, turn, flow) a un fade simple cuando no están soportadas.

jquery-mobile
<!-- Disable transitions for a specific link -->
<a href="#page2" data-transition="none">No animation</a>

<!-- Globally disable (useful for older devices / testing) -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.defaultPageTransition = "none";
  $.mobile.defaultDialogTransition = "none";
});
</script>

<!-- 3D transitions fall back to fade when not supported -->
03

Toolbars (header y footer)

Header y footer fijos

Añade data-position=fixed para mantener un header o footer pegado arriba/abajo del viewport mientras la página hace scroll. Tocar la página alterna la visibilidad de las toolbars por defecto. El contenido de la página recibe padding para no quedar oculto tras las toolbars.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="header" data-position="fixed">
    <h1>Fixed Header</h1>
  </div>
  <div data-role="main" class="ui-content">
    <p>Scroll the page — the toolbars stay in place.</p>
  </div>
  <div data-role="footer" data-position="fixed">
    <h4>Fixed Footer</h4>
  </div>
</div>

Toolbars a pantalla completa

data-fullscreen=true superpone las toolbars fijas sobre el contenido (semitransparentes), en lugar de reservar espacio. Genial para visores de fotos o mapas donde el contenido debe llenar la pantalla. Las toolbars aparecen/desaparecen al tocar, igual que las fijas.

jquery-mobile
<div data-role="page" id="photo">
  <div data-role="header" data-position="fixed" data-fullscreen="true">
    <h1>Photos</h1>
  </div>
  <div data-role="main" class="ui-content">
    <img src="photo.jpg" style="width:100%">
  </div>
  <div data-role="footer" data-position="fixed" data-fullscreen="true">
    <h4>Footer over content</h4>
  </div>
</div>

Toolbars persistentes

Cuando dos páginas tienen footers (o headers) con el mismo data-id y data-position=fixed, la toolbar persiste entre las transiciones de página en lugar de animarse con la página. Este es el patrón estándar de una barra de navegación inferior persistente — solo cambia el enlace activo por página.

jquery-mobile
<!-- Both pages use the SAME data-id so the footer persists -->
<div data-role="page" id="home">
  <div data-role="footer" data-id="main-nav" data-position="fixed">
    <div data-role="navbar">
      <ul><li><a href="#home" class="ui-btn-active">Home</a></li>
      <li><a href="#settings">Settings</a></li></ul>
    </div>
  </div>
</div>

<div data-role="page" id="settings">
  <div data-role="footer" data-id="main-nav" data-position="fixed">
    <div data-role="navbar">
      <ul><li><a href="#home">Home</a></li>
      <li><a href="#settings" class="ui-btn-active">Settings</a></li></ul>
    </div>
  </div>
</div>

Comportamiento de alternancia al tocar

Las toolbars fijas alternan su visibilidad cuando el usuario toca la página. Fija data-tap-toggle=false para mantener una toolbar siempre visible. Opciones relacionadas por elemento: data-hide-during-focus (ocultar cuando los inputs reciben foco) y data-update-page-padding (reaplicar el padding de la página al redimensionar).

jquery-mobile
<!-- Disable tap-to-toggle on a fixed toolbar -->
<div data-role="header" data-position="fixed" data-tap-toggle="false">
  <h1>Always visible</h1>
</div>

<!-- Globally turn off tap toggle -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.toolbar.prototype.options.tapToggle = false;
});
</script>

Tema y botones de la toolbar

Los headers pueden albergar botones posicionados con las clases ui-btn-left / ui-btn-right. data-theme fija la muestra de color de la barra. data-iconpos=notext muestra solo un icono para un aspecto compacto. Los botones dentro de un header se estilizan automáticamente como botones en línea.

jquery-mobile
<div data-role="header" data-theme="b">
  <a href="#" class="ui-btn-left" data-icon="home" data-iconpos="notext">Home</a>
  <h1>Title</h1>
  <a href="#" class="ui-btn-right" data-icon="gear" data-iconpos="notext">Settings</a>
</div>

Actualizar toolbars dinámicamente

Tras cambiar el marcado de una toolbar en tiempo de ejecución, llama a $(el).toolbar('refresh') para reaplicar el estilo y el padding. El widget toolbar (introducido en 1.4) gestiona el posicionamiento fijo y el tap-toggle; inicialízalo manualmente con $().toolbar() si añades una toolbar después de crear la página.

jquery-mobile
<script>
// Update the header title and re-enhance after DOM change
$(function () {
  $("#my-header h1").text("New Title");
  $("#my-header").toolbar("refresh");
});
</script>

<div data-role="header" id="my-header" data-position="fixed">
  <h1>Old Title</h1>
</div>
05

Botones

Fundamentos de los botones

Cualquier <a> con class=ui-btn (o data-role=button), más los <button> y <input type=button|submit|reset>, se mejoran automáticamente en botones con estilo. La clase ui-btn es la forma moderna de marcar un enlace como botón sin depender de data-role.

jquery-mobile
<!-- Anchor button -->
<a href="#" class="ui-btn">Link Button</a>

<!-- <button> and <input> auto-enhanced -->
<button class="ui-btn">Button Element</button>
<input type="button" value="Input Button">
<input type="submit" value="Submit">

<!-- Use data-role explicitly -->
<a href="#" data-role="button">Anchor via role</a>

Botones en línea

Por defecto los botones ocupan el ancho completo (bloque). Añade ui-btn-inline (o data-inline=true) para que un botón sea solo tan ancho como su etiqueta, permitiendo que varios botones queden lado a lado. Útil para filas de acciones como 'Cancelar | Aceptar'.

jquery-mobile
<!-- Inline: only as wide as the content -->
<a href="#" class="ui-btn ui-btn-inline">A</a>
<a href="#" class="ui-btn ui-btn-inline">B</a>
<a href="#" class="ui-btn ui-btn-inline">C</a>

<!-- Default (block) buttons fill the width -->
<a href="#" class="ui-btn">Full-width button</a>

Iconos de botón

Usa ui-icon-{nombre} para añadir un icono y ui-btn-icon-{pos} para colocarlo (left, right, top, bottom, notext). ui-btn-icon-notext oculta el texto y muestra solo el icono — proporciona el texto de todas formas por accesibilidad/lectores de pantalla.

jquery-mobile
<a href="#" class="ui-btn ui-icon-home ui-btn-icon-left">Home</a>
<a href="#" class="ui-btn ui-icon-search ui-btn-icon-right">Search</a>
<a href="#" class="ui-btn ui-icon-gear ui-btn-icon-top">Settings</a>
<a href="#" class="ui-btn ui-icon-star ui-btn-icon-notext">Star (icon only)</a>
<a href="#" class="ui-btn ui-icon-delete ui-btn-icon-bottom">Delete</a>

Posición del icono y en línea

El atributo data-iconpos es el equivalente heredado de las clases ui-btn-icon-*. 'notext' muestra solo el icono (conserva siempre el texto visible para los lectores de pantalla vía el texto del elemento). Puedes combinar libremente las clases de en línea e icono en un mismo botón.

jquery-mobile
<!-- data-* equivalents -->
<a href="#" data-role="button" data-icon="home" data-iconpos="left">Home</a>
<a href="#" data-role="button" data-icon="home" data-iconpos="notext">Home</a>

<!-- Combine inline + icon -->
<a href="#" class="ui-btn ui-btn-inline ui-icon-plus ui-btn-icon-left">Add</a>
<a href="#" class="ui-btn ui-btn-inline ui-icon-minus ui-btn-icon-left">Remove</a>

Botones mini y deshabilitados

Añade ui-mini (o data-mini=true) para un botón más pequeño y compacto — útil en toolbars densas. Deshabilita un botón con ui-state-disabled (o el atributo nativo disabled en <button>/<input>). Los botones deshabilitados ignoran los toques.

jquery-mobile
<!-- Mini (smaller) button -->
<a href="#" class="ui-btn ui-mini">Mini</a>

<!-- Disabled button -->
<a href="#" class="ui-btn ui-state-disabled">Disabled</a>

<!-- Native disabled -->
<button disabled>Disabled button</button>
<input type="submit" value="Go" disabled>

Grupos de botones (controlgroup)

Un controlgroup agrupa visualmente botones — los botones adyacentes comparten esquinas redondeadas y sin huecos. data-type=horizontal los organiza en fila (bueno para controles segmentados); el vertical por defecto los apila. Esto también agrupa checkboxes/radios en un conjunto unificado.

jquery-mobile
<div data-role="controlgroup" data-type="horizontal">
  <a href="#" class="ui-btn">Yes</a>
  <a href="#" class="ui-btn">No</a>
  <a href="#" class="ui-btn">Maybe</a>
</div>

<!-- Vertical group (default) -->
<div data-role="controlgroup">
  <a href="#" class="ui-btn">Option 1</a>
  <a href="#" class="ui-btn">Option 2</a>
</div>
06

List views

Listview básica

Añade data-role=listview a un <ul> para convertirlo en una lista apta para táctil con filas de ancho completo y tocables. Cada <li> que contiene un <a> se convierte en una fila enlazada con una flecha a la derecha. data-inset=true deja la lista con esquinas redondeadas y márgenes en lugar de de borde a borde.

jquery-mobile
<ul data-role="listview" data-inset="true">
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
  <li><a href="#">Cherry</a></li>
</ul>

Listas inset

Las listas de borde a borde ocupan el ancho completo (buenas para menús a pantalla completa); las listas inset tienen esquinas redondeadas y márgenes alrededor (buenas para secciones de contenido dentro de una página). Usa data-inset=true para listas inset, que se parecen más a paneles de ajustes agrupados.

jquery-mobile
<!-- Edge-to-edge (default) -->
<ul data-role="listview">
  <li><a href="#">Item 1</a></li>
</ul>

<!-- Inset: rounded, with margins -->
<ul data-role="listview" data-inset="true">
  <li><a href="#">Item 1</a></li>
  <li><a href="#">Item 2</a></li>
</ul>

Divisores de lista

Un <li> con data-role=list-divider se convierte en un encabezado de sección no clicable. data-autodividers=true inserta automáticamente divisores basados en la primera letra del texto de cada ítem — perfecto para una lista de contactos alfabética.

jquery-mobile
<ul data-role="listview" data-inset="true">
  <li data-role="list-divider">Fruits</li>
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
  <li data-role="list-divider">Vegetables</li>
  <li><a href="#">Carrot</a></li>
</ul>

<!-- Auto dividers from first letter -->
<ul data-role="listview" data-autodividers="true">
  <li><a href="#">Alice</a></li>
  <li><a href="#">Bob</a></li>
</ul>

Burbujas de contador y miniaturas

Añade un span con class=ui-li-count dentro de un <li> para mostrar una burbuja numérica de contador a la derecha. Usa un <img> con class=ui-li-thumb (normalmente 80x80) para una miniatura a la izquierda. Combínalo con <h3>/<p> para filas de lista ricas, como en una app.

jquery-mobile
<ul data-role="listview" data-inset="true">
  <!-- Count bubble -->
  <li><a href="#">Inbox <span class="ui-li-count">12</span></a></li>
  <!-- Thumbnail on the left -->
  <li>
    <a href="#">
      <img src="thumb.jpg" class="ui-li-thumb">
      <h3>Title</h3>
      <p>Description</p>
      <span class="ui-li-count">3</span>
    </a>
  </li>
</ul>

Filtro de búsqueda

data-filter=true añade un input de búsqueda encima de la lista que filtra los ítems por texto en tiempo real. data-filter-placeholder personaliza el aviso. data-filter-reveal=true oculta todos los ítems hasta que el usuario escribe — útil para una búsqueda estilo autocompletado.

jquery-mobile
<ul data-role="listview" data-filter="true"
    data-filter-placeholder="Search fruits...">
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
  <li><a href="#">Cherry</a></li>
</ul>

<!-- Filter reveals hidden items (collapsible search) -->
<ul data-role="listview" data-filter="true" data-filter-reveal="true">
  <li><a href="#">Hidden until searched</a></li>
</ul>

Botones divididos y listas anidadas

Cuando un <li> contiene dos elementos <a>, jQuery Mobile renderiza un botón dividido: la fila principal navega al primer enlace y un botón de icono aparte (fijado con data-split-icon) a la derecha abre el segundo. Un <ul> anidado dentro de un <li> se convierte automáticamente en una subpágina de detalle.

jquery-mobile
<!-- Split button: row link + icon link on the right -->
<ul data-role="listview" data-split-icon="gear" data-inset="true">
  <li>
    <a href="#detail">Go to detail</a>
    <a href="#edit">Edit</a>
  </li>
</ul>

<!-- Nested list (child <ul> becomes a sub-page) -->
<ul data-role="listview">
  <li>Fruits
    <ul>
      <li><a href="#">Apple</a></li>
      <li><a href="#">Banana</a></li>
    </ul>
  </li>
</ul>
07

Controles de formulario

Estructura del formulario y envío AJAX

jQuery Mobile mejora automáticamente los inputs del formulario y envía los formularios vía AJAX por defecto, mostrando un spinner de carga y transicionando a la página de resultado. Fija data-ajax=false para un envío tradicional de página completa (necesario para subidas de archivos que no usen una API moderna).

jquery-mobile
<form action="/submit" method="post" data-ajax="true">
  <label for="name">Name:</label>
  <input type="text" name="name" id="name" placeholder="Your name">

  <button type="submit" class="ui-btn">Submit</button>
</form>

<!-- Disable AJAX for this form (normal full submit) -->
<form action="/upload" method="post" data-ajax="false">...</form>

Inputs de texto y botón de limpiar

Cada tipo de input HTML5 (text, email, tel, number, password, date, etc.) se estiliza de forma consistente. data-clear-btn=true añade un botón de limpiar (x) dentro del campo. Usa data-role=none para mantener un control como input nativo plano sin el estilo de jQuery Mobile.

jquery-mobile
<label for="email">Email</label>
<input type="email" id="email" data-clear-btn="true" placeholder="[email protected]">

<label for="phone">Phone</label>
<input type="tel" id="phone" data-clear-btn="true" data-clear-btn-text="Clear">

<!-- Non-enhanced native input -->
<input type="text" data-role="none">

Contenedores de campo

Envuelve un par etiqueta + control en un div con class=ui-field-contain. En pantallas anchas, la etiqueta y el input quedan lado a lado; en teléfonos estrechos se apilan verticalmente. Este comportamiento responsivo reemplaza al antiguo atributo data-role=fieldcontain.

jquery-mobile
<div class="ui-field-contain">
  <label for="user">Username</label>
  <input type="text" id="user">
</div>

<div class="ui-field-contain">
  <label for="pwd">Password</label>
  <input type="password" id="pwd">
</div>

Input de búsqueda

Un <input type=search> se mejora en un campo de búsqueda con icono de lupa. Emparéjalo con una listview dándole al input un id y fijando data-input=#id en el filter de la listview — así puedes colocar el cuadro de búsqueda en cualquier parte de la página.

jquery-mobile
<label for="q">Search</label>
<input type="search" id="q" placeholder="Search...">

<!-- Search input feeding a listview filter -->
<input type="search" id="my-filter" data-type="search">
<ul data-role="listview" data-filter="true"
    data-input="#my-filter">
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
</ul>

Textarea e inputs ocultos

Los textareas se estilizan para coincidir con los demás inputs y crecen automáticamente al escribir por defecto; fija data-autogrow=false para fijar la altura con una barra de scroll en su lugar. Los inputs ocultos pasan intactos. Como el resto de inputs, envuélvelos en ui-field-contain para etiquetas responsivas.

jquery-mobile
<label for="bio">Bio</label>
<textarea id="bio" placeholder="Tell us about you"></textarea>

<!-- Auto-grow textarea -->
<textarea id="bio" data-autogrow="false"></textarea>

<!-- Hidden inputs are not styled -->
<input type="hidden" name="id" value="42">

Desactivar la auto-mejora

Añade data-role=none a cualquier control para saltarte la mejora de jQuery Mobile y mantenerlo nativo. Para una regla a nivel de proyecto, fija keepNative durante mobileinit a una cadena de selector de elementos que nunca deban mejorarse — útil al mezclar controles con estilo personalizado en páginas de jQM.

jquery-mobile
<!-- Keep a control native (no jQM styling) -->
<select data-role="none">...</select>
<input type="checkbox" data-role="none">

<!-- Globally disable enhancement for a tag -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.page.prototype.options.keepNative = "select, input[type=checkbox]";
});
</script>
08

Sliders

Slider de rango básico

Un <input type=range> con min, max, value y step se mejora en un slider apto para táctil con burbuja de valor. El atributo value fija la posición inicial. El slider escribe su valor de vuelta al input, así que se envía con normalidad con el formulario.

jquery-mobile
<label for="volume">Volume</label>
<input type="range" name="volume" id="volume"
       value="50" min="0" max="100" step="1">

Slider con resaltado

data-highlight=true rellena la pista a la izquierda del tirador con el color del tema activo, dando una imagen clara del nivel actual. Sin él, la pista es un único color plano. Útil para ajustes como el volumen o el brillo.

jquery-mobile
<label for="brightness">Brightness</label>
<input type="range" id="brightness"
       value="70" min="0" max="100"
       data-highlight="true">

Slider mini

data-mini=true renderiza un slider más pequeño y compacto que ocupa menos espacio vertical — práctico al agrupar varios controles en un panel de ajustes. Se comporta igual que el slider normal, solo que con tamaño reducido.

jquery-mobile
<label for="age">Age</label>
<input type="range" id="age" value="25" min="0" max="120"
       data-mini="true" data-highlight="true">

Step y múltiples sliders

step controla el incremento (por ejemplo, step=5 salta a 0, 5, 10, ...). Cada input de rango es un slider independiente; para un rango de doble tirador debes construir un widget personalizado o usar un plugin de terceros. Los atributos nativos value, min y max guían el comportamiento.

jquery-mobile
<label for="temp">Temperature (step 5)</label>
<input type="range" id="temp" value="20" min="0" max="100" step="5">

<!-- Two independent sliders -->
<label for="low">Min</label>
<input type="range" id="low" value="10" min="0" max="100">
<label for="high">Max</label>
<input type="range" id="high" value="90" min="0" max="100">

Eventos del slider

El slider emite slidestart cuando el usuario comienza a arrastrar el tirador y slidestop cuando termina. Para actualizaciones continuas durante el arrastre, enlázate al evento nativo 'input' o 'change' del input de rango subyacente. Lee/escribe el valor con $(el).val().

jquery-mobile
<label for="vol">Volume</label>
<input type="range" id="vol" value="50" min="0" max="100">

<script>
$("#vol").on("slidestart", function () {
  console.log("User started dragging");
});
$("#vol").on("slidestop", function () {
  console.log("Value is now " + $(this).val());
});
</script>
09

Interruptores deslizantes

Interruptor deslizante básico

Un flip switch es un <select> con exactamente dos elementos <option> y data-role=slider. Se renderiza como un interruptor de encendido/apagado estilo iOS. La opción seleccionada determina el estado inicial, y el valor se envía como un select normal (el value de la opción elegida).

jquery-mobile
<label for="notify">Notifications</label>
<select name="notify" id="notify" data-role="slider">
  <option value="off">Off</option>
  <option value="on" selected>On</option>
</select>

Etiquetas personalizadas

El texto de las dos opciones se convierte en las etiquetas de cada lado del interruptor. Puedes usar cualquier texto corto (On/Off, Sí/No, Habilitado/Deshabilitado). Mantén las etiquetas cortas para que encajen en el toggle sin truncarse en pantallas pequeñas.

jquery-mobile
<label for="wifi">Wi-Fi</label>
<select id="wifi" data-role="slider">
  <option value="disabled">Disabled</option>
  <option value="enabled" selected>Enabled</option>
</select>

Interruptor mini

data-mini=true renderiza un interruptor más pequeño que ocupa menos espacio vertical, a juego con los sliders mini y otros controles mini. Emparéja los controles mini juntos en paneles de ajustes densos para un aspecto compacto consistente.

jquery-mobile
<label for="sync">Auto-sync</label>
<select id="sync" data-role="slider" data-mini="true">
  <option value="no">No</option>
  <option value="yes" selected>Yes</option>
</select>

Tema del interruptor

data-theme fija el color del tirador del interruptor, y data-track-theme el color de la pista detrás. Mezclar muestras de color (por ejemplo, un tirador oscuro sobre pista clara) hace que el estado activo sea más distintivo visualmente.

jquery-mobile
<label for="darkmode">Dark mode</label>
<select id="darkmode" data-role="slider"
        data-theme="b" data-track-theme="a">
  <option value="off">Off</option>
  <option value="on" selected>On</option>
</select>

Alternancia programática

Fija el valor con $(el).val(valor) y luego llama a .slider('refresh') para actualizar el interruptor visual en consecuencia. Lee el estado actual con .val(). Refresca siempre tras cambiar programáticamente el valor del select subyacente, o el tirador no se moverá.

jquery-mobile
<select id="power" data-role="slider">
  <option value="off">Off</option>
  <option value="on">On</option>
</select>

<script>
// Turn the switch on programmatically
$("#power").val("on").slider("refresh");
// Read current state
var state = $("#power").val(); // "on" or "off"
</script>
10

Checkboxes y radios

Checkboxes

Un checkbox es un <input type=checkbox> normal envuelto por (o adyacente a) un <label for=id>. jQuery Mobile estiliza la etiqueta como un bloque tocable. Cuando la etiqueta envuelve al input, el atributo for es opcional. El estado marcado se envía como de costumbre con el formulario.

jquery-mobile
<label for="agree"><input type="checkbox" id="agree" name="agree"> I agree</label>

<label for="news"><input type="checkbox" id="news" name="news" checked> Newsletter</label>

<!-- Wrap in ui-field-contain for layout -->
<div class="ui-field-contain">
  <label for="agree">I agree to terms</label>
  <input type="checkbox" id="agree">
</div>

Botones de radio

Agrupa los radios dándoles el mismo atributo name. Envuelve el grupo en un fieldset con data-role=controlgroup (y un <legend>) para agruparlos visualmente con esquinas compartidas. Solo un radio de un grupo con el mismo nombre puede estar marcado a la vez.

jquery-mobile
<fieldset data-role="controlgroup">
  <legend>Choose a color:</legend>
  <label for="r"><input type="radio" name="color" id="r" value="red" checked> Red</label>
  <label for="g"><input type="radio" name="color" id="g" value="green"> Green</label>
  <label for="b"><input type="radio" name="color" id="b" value="blue"> Blue</label>
</fieldset>

Controlgroups horizontales

data-type=horizontal dispone los checkboxes o radios en una sola fila como control segmentado en lugar de pila vertical. Es compacto y funciona bien con etiquetas cortas (S/M/L, Sí/No). Mantén las etiquetas cortas para que encajen en pantallas estrechas.

jquery-mobile
<fieldset data-role="controlgroup" data-type="horizontal">
  <legend>Size:</legend>
  <label for="s"><input type="radio" name="size" id="s" value="s" checked> S</label>
  <label for="m"><input type="radio" name="size" id="m" value="m"> M</label>
  <label for="l"><input type="radio" name="size" id="l" value="l"> L</label>
</fieldset>

Mini y tema

data-mini=true reduce los controles, y data-theme fija la muestra de color aplicada cuando un ítem está marcado/activo. Tematiza el estado activo para que destaque sobre el fondo de la página. Estas opciones se aplican al controlgroup completo a la vez.

jquery-mobile
<fieldset data-role="controlgroup" data-mini="true" data-theme="b">
  <label for="a"><input type="checkbox" id="a"> Option A</label>
  <label for="b"><input type="checkbox" id="b"> Option B</label>
</fieldset>

Refrescar tras el cambio

Tras fijar la propiedad checked de un checkbox/radio en código, llama a .checkboxradio('refresh') para que el visual mejorado coincida. Si añades o quitas inputs dentro de un controlgroup en tiempo de ejecución, llama a .controlgroup('refresh') para reaplicar el estilo agrupado.

jquery-mobile
<input type="checkbox" id="c1">

<script>
// Check programmatically and update the visual state
$("#c1").prop("checked", true).checkboxradio("refresh");

// For a controlgroup, refresh the group after adding/removing items
$("#grp").controlgroup("refresh");
</script>
11

Menús de selección

Select nativo

Por defecto jQuery Mobile muestra un select con estilo personalizado, pero el selector del sistema operativo subyacente sigue abriéndose. Fija data-native-menu=true (o data-role=none) para usar por completo el desplegable nativo del dispositivo — más rápido y familiar, pero menos consistente visualmente entre plataformas.

jquery-mobile
<label for="country">Country</label>
<select id="country" data-native-menu="true">
  <option value="us">United States</option>
  <option value="ca">Canada</option>
  <option value="uk">United Kingdom</option>
</select>

<!-- data-role="none" also keeps it fully native -->
<select data-role="none">...</select>

Menú de selección personalizado

data-native-menu=false abre un menú emergente con estilo de jQuery Mobile en lugar del selector nativo, dando un aspecto consistente en cualquier dispositivo. En un teléfono aparece como un diálogo a pantalla completa con un botón 'Done'; en una tablet como un popup menor cerca del campo.

jquery-mobile
<label for="fruit">Fruit</label>
<select id="fruit" data-native-menu="false">
  <option value="apple">Apple</option>
  <option value="banana">Banana</option>
  <option value="cherry">Cherry</option>
</select>

Placeholder y multiple

Una primera opción con valor vacío actúa como placeholder. data-overlay-theme fija el color del fondo de la capa tras el menú personalizado. Añadir el atributo multiple convierte el menú personalizado en un diálogo de lista de verificación donde el usuario puede elegir varias opciones, mostradas separadas por comas en el botón.

jquery-mobile
<label for="color">Color</label>
<select id="color" data-native-menu="false" data-overlay-theme="b">
  <option value="">Choose a color...</option>
  <option value="red">Red</option>
  <option value="green">Green</option>
</select>

<!-- Multiple selection (renders as a checklist dialog) -->
<label for="tags">Tags</label>
<select id="tags" multiple data-native-menu="false">
  <option value="a">A</option>
  <option value="b">B</option>
</select>

Tema y overlay del select

data-theme estiliza el propio botón del select; data-overlay-theme fija el color del popup/fondo; data-divider-theme colorea los separadores list-divider dentro del menú. Puedes insertar elementos <li data-role=list-divider> entre las opciones para agruparlas visualmente.

jquery-mobile
<label for="size">Size</label>
<select id="size" data-native-menu="false"
        data-theme="a" data-overlay-theme="b" data-divider-theme="a">
  <option value="s">Small</option>
  <option value="m">Medium</option>
  <li data-role="list-divider">Large sizes</li>
  <option value="l">Large</option>
</select>

Eventos del select

Escucha el evento estándar 'change' para reaccionar a una selección. Tras cambiar el valor (o reemplazar las opciones) en código, llama a .selectmenu('refresh') para que la etiqueta del botón se actualice a la nueva selección. Reconstruye el menú con 'refresh', no reinicializando.

jquery-mobile
<label for="city">City</label>
<select id="city" data-native-menu="false">
  <option value="ny">New York</option>
  <option value="la">Los Angeles</option>
</select>

<script>
$("#city").on("change", function () {
  console.log("Selected: " + $(this).val());
});
// Update options then refresh
$("#city").val("la").selectmenu("refresh");
</script>
12

Popups

Popup básico

Un popup es un div con data-role=popup. Ábrelo enlazando a su id con data-rel=popup. El popup superpone la página centrado por defecto. Añade ui-content para el padding, y usa data-rel=back en un enlace interior para cerrarlo.

jquery-mobile
<a href="#myPopup" data-rel="popup" class="ui-btn">Open popup</a>

<div data-role="popup" id="myPopup" class="ui-content">
  <p>This is a popup.</p>
  <a href="#" class="ui-btn" data-rel="back">Close</a>
</div>

Transiciones del popup

Usa data-transition en el enlace de apertura (o en el propio popup) para elegir la animación. pop y fade son las más naturales para popups. El mismo conjunto de transiciones usado para páginas se aplica aquí; la acción de cierre invierte la transición automáticamente.

jquery-mobile
<a href="#p" data-rel="popup" data-transition="pop">Pop</a>
<a href="#p" data-rel="popup" data-transition="fade">Fade</a>
<a href="#p" data-rel="popup" data-transition="slidedown">Slide down</a>

<div data-role="popup" id="p" class="ui-content" data-theme="a">
  <p>Transitioned in.</p>
</div>

Posicionamiento del popup

data-position-to controla dónde aparece el popup: 'origin' (el elemento que lo abrió, por defecto), '#algunId' (un elemento concreto) o 'window' (centrado en pantalla). También puedes pasar coordenadas x/y al abrir programáticamente con popup('open', x, y).

jquery-mobile
<!-- Position relative to an element / coordinates -->
<a href="#tip" data-rel="popup" data-position-to="origin">Tip (on the link)</a>
<a href="#tip" data-rel="popup" data-position-to="#target">Tip (on #target)</a>
<a href="#tip" data-rel="popup" data-position-to="window">Centered</a>

<div data-role="popup" id="tip" class="ui-content">
  <p>Positioned popup.</p>
</div>

Menú popup y tooltip

Un popup puede contener cualquier contenido — una listview se convierte en menú contextual, un párrafo en tooltip. Estiliza el popup con data-theme y el contenido interior con su propio tema. Los popups se cierran automáticamente cuando el usuario toca fuera (salvo data-dismissible=false).

jquery-mobile
<a href="#menu" data-rel="popup" class="ui-btn">Menu</a>
<div data-role="popup" id="menu" data-theme="b">
  <ul data-role="listview" data-inset="true" data-theme="d">
    <li data-role="divider">Actions</li>
    <li><a href="#">Edit</a></li>
    <li><a href="#">Share</a></li>
    <li><a href="#">Delete</a></li>
  </ul>
</div>

Popup de diálogo

Un popup posicionado en el centro de la ventana con un botón de cierre actúa como diálogo modal. Añade un botón X (ui-icon-delete con ui-btn-icon-notext) en la esquina. Acota el ancho con un estilo max-width para un verdadero aspecto de diálogo en lugar de una hoja de ancho completo.

jquery-mobile
<a href="#dlg" data-rel="popup" data-position-to="window"
   data-transition="pop" class="ui-btn">Open dialog</a>

<div data-role="popup" id="dlg" data-theme="a" class="ui-content"
     style="max-width:400px;">
  <a href="#" data-rel="back" class="ui-btn ui-corner-all ui-icon-delete
     ui-btn-icon-notext ui-btn-right">Close</a>
  <h3>Confirm</h3>
  <p>Are you sure?</p>
  <a href="#" class="ui-btn ui-btn-b" data-rel="back">Yes</a>
  <a href="#" class="ui-btn" data-rel="back">No</a>
</div>

Apertura programática y dismissible

Abre o cierra un popup desde código con .popup('open'/'close'). data-dismissible=false impide el cierre tocando fuera, forzando al usuario a usar un botón de Cerrar — ideal para confirmaciones obligatorias. Puedes pasar coordenadas x/y o un objeto de posición al abrir.

jquery-mobile
<div data-role="popup" id="p2" data-dismissible="false">
  <p>Cannot close by tapping outside.</p>
  <a href="#" class="ui-btn" data-rel="back">Close</a>
</div>

<script>
// Open programmatically (optionally at coordinates)
$("#p2").popup("open");
$("#p2").popup("open", { x: 100, y: 200 });
// Close programmatically
$("#p2").popup("close");
</script>
13

Paneles

Panel básico

Un panel es un div con data-role=panel, colocado dentro de una página (normalmente antes del header). Ábrelo enlazando a su id con un botón. Usa data-rel=close en un enlace interior para cerrar el panel. Los paneles son perfectos para menús de navegación deslizantes.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="panel" id="myPanel">
    <h2>Menu</h2>
    <p>Panel content here.</p>
    <a href="#" class="ui-btn" data-rel="close">Close</a>
  </div>

  <div data-role="header">
    <a href="#myPanel" class="ui-btn ui-btn-inline ui-corner-all ui-icon-bars ui-btn-icon-notext">Menu</a>
    <h1>Home</h1>
  </div>
  <div data-role="main" class="ui-content">
    <p>Page content.</p>
  </div>
</div>

Modos de visualización del panel

data-display controla la animación de apertura: 'reveal' (por defecto) desliza la página a un lado para descubrir el panel debajo; 'overlay' desliza el panel sobre la página; 'push' mueve tanto el panel como la página. Overlay es el más común para menús.

jquery-mobile
<div data-role="panel" id="p1" data-display="reveal">Reveal</div>
<div data-role="panel" id="p2" data-display="overlay">Overlay</div>
<div data-role="panel" id="p3" data-display="push">Push</div>

<!-- data-display controls how the panel interacts with the page:
     reveal : panel sits under the page, page slides away
     overlay: panel slides over the page (page stays)
     push   : both panel and page slide -->

Posición del panel

data-position=left (por defecto) o right fija desde qué lado se desliza el panel. Puedes tener un panel izquierdo y uno derecho en la misma página. Solo un panel puede estar abierto a la vez; abrir un segundo cierra el primero.

jquery-mobile
<!-- Left panel (default) -->
<div data-role="panel" id="leftP" data-position="left">Left</div>

<!-- Right panel -->
<div data-role="panel" id="rightP" data-position="right">Right</div>

<a href="#leftP" class="ui-btn">Open left</a>
<a href="#rightP" class="ui-btn">Open right</a>

Dismissible y swipe

data-dismissible=true (por defecto) cierra el panel cuando el usuario toca fuera de él. data-swipe-close=true permite al usuario deslizar en dirección contraria para cerrarlo (por ejemplo, deslizar a la derecha cierra un panel izquierdo). Ambos están activados por defecto en los paneles overlay.

jquery-mobile
<div data-role="panel" id="p"
     data-dismissible="true"
     data-swipe-close="true"
     data-position="left"
     data-display="overlay">
  <p>Tap outside or swipe to close.</p>
</div>

Eventos del panel

Los paneles disparan los eventos panelbeforeopen, panelopen, panelbeforeclose y panelclose. Devolver false desde un manejador 'before' cancela la acción — útil para confirmar antes de cerrar. Abre/cierra desde código con .panel('open'/'close').

jquery-mobile
<div data-role="panel" id="p">...</div>

<script>
$("#p").on("panelopen", function () {
  console.log("Panel opened");
});
$("#p").on("panelbeforeclose", function () {
  // return false here to prevent closing
  console.log("About to close");
});
$("#p").on("panelclose", function () {
  console.log("Panel closed");
});

// Open / close programmatically
$("#p").panel("open");
$("#p").panel("close");
</script>
14

Collapsibles

Collapsible básico

Un div con data-role=collapsible envuelve un encabezado (h1-h6) como cabecera clicable y el resto como contenido expandible. Empieza colapsado por defecto. Hacer clic en el encabezado alterna el contenido abierto/cerrado con un icono +/-.

jquery-mobile
<div data-role="collapsible">
  <h3>Section title</h3>
  <p>Hidden content shown when expanded.</p>
  <p>Click the header to toggle.</p>
</div>

Iconos y tema del collapsible

Personaliza el indicador con data-collapsed-icon y data-expanded-icon (más/menos por defecto). data-theme estiliza el encabezado; data-content-theme estiliza el área de contenido expandida. data-collapsed=false hace que la sección empiece expandida en lugar de colapsada.

jquery-mobile
<div data-role="collapsible"
     data-collapsed-icon="carat-r"
     data-expanded-icon="carat-d"
     data-theme="b" data-content-theme="a"
     data-collapsed="false">
  <h3>Initially open</h3>
  <p>Custom icons and theme.</p>
</div>

Conjunto de collapsibles (acordeón)

Un collapsibleset agrupa collapsibles de modo que solo uno esté abierto a la vez — un acordeón. Abrir uno cierra automáticamente los demás. (En 1.4 el atributo es data-role=collapsibleset; el nombre antiguo collapsible-set sigue funcionando.) El conjunto completo comparte un tema unificado.

jquery-mobile
<div data-role="collapsibleset" data-theme="a" data-content-theme="a">
  <div data-role="collapsible">
    <h3>Section 1</h3>
    <p>Only one section open at a time.</p>
  </div>
  <div data-role="collapsible" data-collapsed="false">
    <h3>Section 2 (open by default)</h3>
    <p>Opening this closes Section 1.</p>
  </div>
  <div data-role="collapsible">
    <h3>Section 3</h3>
    <p>Third section.</p>
  </div>
</div>

Preexpandidos e inset

En un collapsibleset, fija data-collapsed=false en la sección que quieras abierta al inicio. data-inset=true (por defecto en los conjuntos) da al grupo esquinas redondeadas y márgenes. Los conjuntos de borde a borde usan data-inset=false para ocupar el ancho completo.

jquery-mobile
<!-- A set always starts with one open by default; control with data-collapsed -->
<div data-role="collapsibleset" data-inset="true">
  <div data-role="collapsible" data-collapsed="false">
    <h3>Open first</h3>
    <p>Content</p>
  </div>
  <div data-role="collapsible">
    <h3>Closed second</h3>
    <p>Content</p>
  </div>
</div>

Collapsible con listview

Un collapsible puede contener cualquier widget, incluida una listview. Es un gran patrón para agrupar una lista larga bajo un encabezado colapsable. Añade data-filter=true al collapsible para filtrar los ítems de la listview interior vía un cuadro de búsqueda dentro del área del encabezado.

jquery-mobile
<div data-role="collapsible" data-filter="true">
  <h3>Contacts</h3>
  <ul data-role="listview">
    <li><a href="#">Alice</a></li>
    <li><a href="#">Bob</a></li>
    <li><a href="#">Carol</a></li>
  </ul>
</div>

Expandir/colapsar programáticamente

Controla un collapsible desde código con .collapsible('expand') y .collapsible('collapse'). Escucha los eventos 'collapse' y 'expand' para reaccionar a la alternancia del usuario. En un conjunto, expandir una sección programáticamente colapsa automáticamente las demás.

jquery-mobile
<div data-role="collapsible" id="c">
  <h3>Section</h3>
  <p>Content</p>
</div>

<script>
// Expand or collapse from code
$("#c").collapsible("expand");
$("#c").collapsible("collapse");
// Toggle based on current state
$("#c h3").click(); // simplest manual toggle
</script>
15

Pestañas

Pestañas básicas

Un widget de pestañas es un div con data-role=tabs que contiene una navbar (los enlaces de las pestañas) y paneles de contenido cuyos ids coinciden con los href de los enlaces. El enlace con ui-btn-active se muestra primero. Hacer clic en una pestaña muestra su panel y oculta los demás — sin transición de página.

jquery-mobile
<div data-role="tabs" id="myTabs">
  <div data-role="navbar">
    <ul>
      <li><a href="#tab1" class="ui-btn-active">One</a></li>
      <li><a href="#tab2">Two</a></li>
      <li><a href="#tab3">Three</a></li>
    </ul>
  </div>
  <div id="tab1" class="ui-body-d ui-content">Content 1</div>
  <div id="tab2" class="ui-body-d ui-content">Content 2</div>
  <div id="tab3" class="ui-body-d ui-content">Content 3</div>
</div>

Pestañas con iconos

Añade las clases ui-icon-{nombre} y ui-btn-icon-top a los enlaces de las pestañas para mostrar iconos sobre las etiquetas, dando una barra de pestañas estilo app. La pestaña activa conserva ui-btn-active. Usa ui-btn-icon-top para que el icono quede sobre el texto en la tira de pestañas.

jquery-mobile
<div data-role="tabs">
  <div data-role="navbar">
    <ul>
      <li><a href="#t1" class="ui-btn-active ui-icon-home ui-btn-icon-top">Home</a></li>
      <li><a href="#t2" class="ui-icon-search ui-btn-icon-top">Search</a></li>
      <li><a href="#t3" class="ui-icon-gear ui-btn-icon-top">Settings</a></li>
    </ul>
  </div>
  <div id="t1" class="ui-content">Home tab</div>
  <div id="t2" class="ui-content">Search tab</div>
  <div id="t3" class="ui-content">Settings tab</div>
</div>

Pestañas AJAX

Cuando el href de un enlace de pestaña es una URL (no #id), el widget de pestañas carga esa página vía AJAX en el contenedor al activarse. La primera pestaña se carga automáticamente al inicializarse la página. Útil para cargar con pereza contenido pesado por pestaña.

jquery-mobile
<div data-role="tabs">
  <div data-role="navbar">
    <ul>
      <li><a href="ajax-tab1.html" class="ui-btn-active">One</a></li>
      <li><a href="ajax-tab2.html">Two</a></li>
    </ul>
  </div>
  <!-- The first tab's content is loaded into this container -->
  <div class="ui-content" id="ajax-content"></div>
</div>

Persistencia de las pestañas

Las pestañas no recuerdan su estado activo entre recargas por defecto. Usa el evento tabsactivate (que da ui.newPanel/ui.oldPanel) más localStorage para persistir la selección. Vuelve a disparar el clic de la pestaña guardada al cargar para restaurarla.

jquery-mobile
<div data-role="tabs" id="t">
  <div data-role="navbar">
    <ul>
      <li><a href="#a" class="ui-btn-active">A</a></li>
      <li><a href="#b">B</a></li>
    </ul>
  </div>
  <div id="a" class="ui-content">A</div>
  <div id="b" class="ui-content">B</div>
</div>

<script>
// Remember the active tab across reloads
var saved = localStorage.getItem("activeTab") || "#a";
$("#t a[href='" + saved + "']").click();
$("#t").on("tabsactivate", function (e, ui) {
  localStorage.setItem("activeTab", "#" + ui.newPanel.attr("id"));
});
</script>

Eventos de pestaña

tabsbeforeactivate se dispara antes de cambiar de pestaña (devuelve false para cancelar); tabsactivate se dispara después. Ambos dan ui.newTab/ui.oldTab (los enlaces <a>) y ui.newPanel/ui.oldPanel (los divs de contenido). Úsalos para cargar contenido con pereza, registrar analítica o validar antes de cambiar.

jquery-mobile
<div data-role="tabs" id="t">...</div>

<script>
$("#t").on("tabsbeforeactivate", function (e, ui) {
  // ui.newTab, ui.oldTab, ui.newPanel, ui.oldPanel
  // return false to cancel the switch
  console.log("Switching to", ui.newPanel.attr("id"));
});
$("#t").on("tabsactivate", function (e, ui) {
  console.log("Now showing", ui.newPanel.attr("id"));
});
</script>
16

Tematización

Muestras de tema (a-e)

La tematización de jQuery Mobile usa 'muestras' con letras (a-e) en lugar de un solo color. a es la de mayor contraste (oscura) y es la predeterminada para headers/footers; b es un acento azul; c es el fondo claro por defecto de la página. Aplica una muestra con data-theme en cualquier elemento.

jquery-mobile
<!-- jQuery Mobile ships with 5 swatches: a, b, c, d, e -->
<!-- a = black (high contrast), b = blue, c = light gray,
     d = medium gray, e = yellow -->

<div data-role="page" data-theme="b">
  <div data-role="header" data-theme="a"><h1>Dark header</h1></div>
  <div data-role="main" class="ui-content">Page body</div>
  <div data-role="footer" data-theme="a"><h4>Dark footer</h4></div>
</div>

Aplicar temas

Para los botones usa la clase ui-btn-{muestra} (por ejemplo, ui-btn-b para un botón azul). Para otros elementos usa data-theme={muestra}. Un hijo hereda la muestra de su padre salvo que fijes una explícitamente. La muestra de página por defecto es 'c' (gris claro).

jquery-mobile
<!-- Per element -->
<a href="#" class="ui-btn ui-btn-a">Swatch A button</a>
<a href="#" class="ui-btn ui-btn-b">Swatch B button</a>

<!-- On bars, lists, forms -->
<div data-role="header" data-theme="b">...</div>
<ul data-role="listview" data-theme="c">...</ul>
<input type="text" data-theme="b">

Tema de overlay

data-overlay-theme fija el color del fondo atenuado detrás de un popup, diálogo o menú de selección personalizado. Usa una muestra oscura (a o b) para el overlay para que el contenido en primer plano destaque. El data-theme del propio popup controla el color de la caja del popup.

jquery-mobile
<!-- Overlay theme for popups, dialogs, custom selects -->
<div data-role="popup" id="p" data-overlay-theme="b" data-theme="a"
     class="ui-content">
  <p>Dark backdrop, light popup.</p>
</div>

<a href="#p" data-rel="popup" data-transition="pop" class="ui-btn">Open</a>

Temas de listas y botones

Las listviews aceptan temas separados: data-theme para las filas, data-divider-theme para los encabezados divisores y data-count-theme para las burbujas de contador. Esto te permite resaltar los divisores manteniendo las filas sutiles. La misma tematización fina se aplica a botones y formularios.

jquery-mobile
<ul data-role="listview" data-theme="d" data-divider-theme="b"
    data-count-theme="b" data-inset="true">
  <li data-role="list-divider">Group (swatch b)</li>
  <li><a href="#">Item (swatch d) <span class="ui-li-count">5</span></a></li>
</ul>

Muestras personalizadas

Cada muestra es solo un conjunto de clases CSS (.ui-bar-{x}, .ui-body-{x}, .ui-btn-up-{x}, etc.). Para añadir una muestra personalizada 'f', copia estas reglas y recolórealas — o usa la herramienta ThemeRoller para generar un archivo de tema personalizado completo. Luego refiérete a ella con data-theme=f.

jquery-mobile
/* Add a custom swatch 'f' by copying the .ui-bar-f, .ui-body-f,
   .ui-btn-up-f, .ui-btn-hover-f, .ui-btn-down-f rules and changing
   the colors. ThemeRoller generates these for you. */
.ui-bar-f { background: #6c2; color: #fff; }
.ui-body-f { background: #efe; color: #030; }
.ui-btn-up-f { background: #6c2; color: #fff; }
.ui-btn-hover-f { background: #5b1; color: #fff; }

<!-- Use it like any built-in swatch -->
<div data-role="header" data-theme="f"><h1>Green header</h1></div>

Herencia de tema

Los elementos heredan la muestra del ancestro más cercano cuando no fijan la suya. Fija una muestra en un nivel alto (por ejemplo, en la página) para tematizar el interior completo consistentemente, y luego sobrescribe elementos individuales según necesites. Cambia el tema de página global por defecto durante mobileinit.

jquery-mobile
<div data-role="page" data-theme="b">
  <!-- Inherits swatch b unless overridden -->
  <div data-role="main" class="ui-content">
    <a href="#" class="ui-btn">Inherits b</a>
    <a href="#" class="ui-btn ui-btn-a">Explicit a</a>
    <a href="#" class="ui-btn" data-theme="a">Explicit a (attr)</a>
  </div>
</div>

<!-- Global default swatch -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.page.prototype.options.theme = "b";
});
</script>
17

Layout responsivo

Layout de cuadrícula

Las cuadrículas son clases CSS, no widgets. ui-grid-a hace una cuadrícula de 2 columnas, ui-grid-b es de 3, hasta ui-grid-d (5 columnas). Los hijos reciben ui-block-a, ui-block-b, ... en orden y se envuelven automáticamente. Las cuadrículas son siempre del 100% de ancho y no responden a breakpoints por sí solas.

jquery-mobile
<!-- 2-column grid (ui-grid-a) -->
<div class="ui-grid-a">
  <div class="ui-block-a"><div class="ui-bar">A</div></div>
  <div class="ui-block-b"><div class="ui-bar">B</div></div>
</div>

<!-- 3-column grid (ui-grid-b), 4 = ui-grid-c, 5 = ui-grid-d -->
<div class="ui-grid-b">
  <div class="ui-block-a">A</div>
  <div class="ui-block-b">B</div>
  <div class="ui-block-c">C</div>
</div>

Cuadrículas responsivas

Las cuadrículas de jQuery Mobile no tienen breakpoints integrados, pero puedes añadir una media query personalizada: en anchos estrechos fija los bloques a width:100% y float:none para que se apilen verticalmente, y en pantallas anchas deja que las columnas por defecto se apliquen. Añade una clase marcadora para acotar la regla.

jquery-mobile
<style>
/* Stack grid columns on phones, side-by-side on tablets */
@media (max-width: 40em) {
  .ui-responsive .ui-block-a,
  .ui-responsive .ui-block-b { width: 100%; float: none; }
}
</style>

<div class="ui-grid-a ui-responsive">
  <div class="ui-block-a">Left (stacks on phone)</div>
  <div class="ui-block-b">Right (stacks on phone)</div>
</div>

Tabla reflow

Una tabla reflow (data-mode=reflow) se reorganiza en un layout de tarjetas apiladas en pantallas estrechas, repitiendo el encabezado de cada columna como etiqueta junto a su valor. Añade la clase ui-responsive para que el reflow solo actúe por debajo del breakpoint, manteniendo una tabla normal en pantallas anchas.

jquery-mobile
<table data-role="table" data-mode="reflow" class="ui-responsive">
  <thead><tr><th>Name</th><th>Age</th><th>City</th></tr></thead>
  <tbody>
    <tr><td>Alice</td><td>30</td><td>NYC</td></tr>
    <tr><td>Bob</td><td>25</td><td>LA</td></tr>
  </tbody>
</table>

<!-- On narrow screens each cell shows its column header as a label -->

Tabla column toggle

Una tabla columntoggle añade un botón 'Columns...' que permite a los usuarios elegir qué columnas mostrar. Asigna data-priority=1..6 a las columnas opcionales (menor = más importante, mostrada en breakpoints más anchos); las columnas sin prioridad se muestran siempre. Las columnas más importantes permanecen en teléfonos; el resto se guardan en el menú.

jquery-mobile
<table data-role="table" data-mode="columntoggle"
       class="ui-responsive" id="tbl">
  <thead>
    <tr>
      <th data-priority="1">Rank</th>
      <th data-priority="2">Name</th>
      <th>Team</th>           <!-- priority 'persist' (always shown) -->
      <th data-priority="3">Points</th>
      <th data-priority="4">Wins</th>
    </tr>
  </thead>
  <tbody><tr><td>1</td><td>Alice</td><td>Red</td><td>100</td><td>10</td></tr></tbody>
</table>

Breakpoints y clases auxiliares

jQuery Mobile no tiene clases utilitarias de breakpoint; escribes tus propias media queries para layouts personalizados. El breakpoint integrado de 40em (640px) solo gobierna cuándo las tablas responsivas (ui-responsive) cambian entre modo apilado y tabular. Para cuadrículas y paneles, define tus propios breakpoints con consultas basadas en em.

jquery-mobile
<!-- jQuery Mobile doesn't ship breakpoint classes like Bootstrap,
     but you can combine media queries with jQM structure. -->

<style>
@media (min-width: 45em) { /* tablet+ */
  .split { width: 50%; float: left; box-sizing: border-box; padding: 0 .5em; }
}
</style>

<div class="split">Left panel</div>
<div class="split">Right panel</div>

<!-- ui-responsive class triggers table breakpoints at 40em (640px) -->
18

Eventos táctiles

Tap y taphold

tap se dispara con un toque rápido (más rápido y fiable que click en móvil, que espera ~300ms). taphold se dispara cuando el usuario mantiene el dedo pulsado ~750ms. Ambos se normalizan para funcionar con ratón y táctil, así que el mismo código corre en escritorio y móvil.

jquery-mobile
<div id="box" class="ui-bar">Tap or hold me</div>

<script>
$("#box").on("tap", function () {
  $(this).css("background", "yellow");
});
$("#box").on("taphold", function () {
  $(this).css("background", "red");
});
</script>

Swipe y dirección

swipe se dispara ante cualquier deslizamiento horizontal; swipeleft y swiperight te dicen la dirección — práctico para carruseles de imágenes o navegación de páginas. Se basan en movimiento horizontal; el scroll vertical intencionalmente no se trata como swipe para que el scroll normal de la página siga funcionando.

jquery-mobile
<div id="card" class="ui-bar">Swipe me</div>

<script>
$("#card").on("swipe", function () {
  console.log("Swiped in any direction");
});
$("#card").on("swipeleft", function () {
  $(this).text("Swiped left -> next");
});
$("#card").on("swiperight", function () {
  $(this).text("Swiped right -> prev");
});
</script>

Umbrales de swipe

Un swipe solo se registra si cubre al menos horizontalDistanceThreshold (30px por defecto) dentro de durationThreshold (1000ms por defecto), y se mantiene bajo verticalDistanceThreshold verticalmente. Sube el umbral horizontal para exigir deslizamientos más largos; bájalo para una sensación más sensible. Fija estos valores durante mobileinit.

jquery-mobile
<script>
// Globally tune swipe sensitivity (bind before jQM loads)
$(document).on("mobileinit", function () {
  $.event.special.swipe.horizontalDistanceThreshold = 60; // px, default 30
  $.event.special.swipe.durationThreshold = 800;          // ms, default 1000
  $.event.special.swipe.verticalDistanceThreshold = 40;   // px, default 75
});
</script>

<script src="jquery.mobile-1.4.5.min.js"></script>

Eventos virtuales de ratón

Los eventos vmouse* son los eventos unificados de ratón/táctil/puntero de jQuery Mobile — se disparan consistentemente ya sea que el usuario use un dedo o un ratón. Usa vclick en lugar de click para evitar el retraso de 300ms en móvil. Son los cimientos sobre los que se construyen tap y swipe.

jquery-mobile
<script>
// vmouse events unify mouse + touch + pointer
$("#el").on("vmousedown", function () { /* finger down / mouse down */ });
$("#el").on("vmouseup",   function () { /* finger up / mouse up   */ });
$("#el").on("vmousemove", function () { /* drag                    */ });
$("#el").on("vmouseover", function () { /* hover-in (best-effort)  */ });
$("#el").on("vmouseout",  function () { /* hover-out (best-effort) */ });
$("#el").on("vclick",     function () { /* tap/click unified       */ });
</script>

Cambio de orientación

orientationchange se dispara al rotar el dispositivo, con e.orientation igual a 'portrait' o 'landscape'. Envuelve el código dependiente del layout en un setTimeout corto porque las dimensiones del viewport se actualizan ligeramente después de dispararse el evento. Escucha el evento 'resize' como respaldo en dispositivos sin giroscopio.

jquery-mobile
<script>
$(window).on("orientationchange", function (e) {
  // e.orientation is "portrait" or "landscape"
  console.log("Now " + e.orientation);
});

// React after the rotation finishes (layout is settled)
$(window).on("orientationchange", function (e) {
  setTimeout(function () {
    $("body").removeClass("portrait landscape").addClass(e.orientation);
  }, 300);
});
</script>

Scroll y throttling

scrollstart y scrollstop son los eventos de scroll con throttle de jQuery Mobile (el navegador hace throttle de los manejadores de scroll de forma nativa, pero estos dan momentos claros de inicio/fin). Para impedir scroll/zoom sobre un elemento — por ejemplo, un canvas de dibujo o un mapa — enlázate a touchmove y devuelve false.

jquery-mobile
<script>
// scrollstart / scrollstop are throttled for performance
$(document).on("scrollstart", function () {
  $("#hint").hide();
});
$(document).on("scrollstop", function () {
  $("#hint").show();
});

// Silence touch scroll on a specific element
$("#canvas").on("touchmove", false);
</script>
19

Eventos y ciclo de vida de la página

Eventos de inicialización de página

pagebeforecreate se dispara antes de que jQuery Mobile mejore el marcado de la página — el mejor lugar para inyectar clases o widgets para que también se mejoren. pagecreate se dispara justo tras completarse la mejora — úsalo para enlazar manejadores de eventos e inicializar plugins. Cada uno se dispara una vez por página.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="main" class="ui-content">
    <a href="#second" class="ui-btn">Go to second</a>
  </div>
</div>

<script>
$(document).on("pagebeforecreate", "#home", function () {
  // Before enhancement — good place to add classes/widgets
});
$(document).on("pagecreate", "#home", function () {
  // After enhancement, before show — bind widgets here
  console.log("Home page created");
});
</script>

Mostrar y ocultar página

pagebeforeshow/pageshow se disparan antes/después de que una página se vuelva visible; pagebeforehide/pagehide se disparan antes/después de que se oculte. Los eventos 'show' se disparan cada vez que la página se muestra (no solo una vez), así que son el lugar adecuado para refrescar datos dinámicos al volver a una página.

jquery-mobile
<script>
$(document).on("pagebeforeshow", "#home", function () {
  console.log("About to show home");
});
$(document).on("pageshow", "#home", function () {
  console.log("Home shown (transition done)");
});
$(document).on("pagebeforehide", "#home", function () {
  console.log("About to leave home");
});
$(document).on("pagehide", "#home", function () {
  console.log("Home hidden");
});
</script>

Page before change

pagebeforechange se dispara antes de cualquier navegación y es el lugar para interceptarla o redirigirla (llama a preventDefault para cancelar). pagechange se dispara tras una navegación exitosa; pagechangefailed se dispara si falló la carga de la página objetivo. Estos se disparan tanto para navegaciones internas (#id) como AJAX.

jquery-mobile
<script>
$(document).on("pagebeforechange", function (e, data) {
  // data.toPage is the target (URL string or jQuery object)
  // data.options has transition, reverse, etc.
  // return false (or e.preventDefault()) to cancel navigation
  if (typeof data.toPage === "string" && data.toPage.indexOf("block") > -1) {
    e.preventDefault();
    alert("Blocked");
  }
});
$(document).on("pagechange", function (e, data) {
  console.log("Navigation completed");
});
$(document).on("pagechangefailed", function (e, data) {
  console.log("Navigation failed");
});
</script>

Carga del page container

pageload se dispara cuando una página obtenida por AJAX se inserta con éxito en el DOM (se proporcionan data.url y data.page). pageloadfailed se dispara ante un error de carga — por defecto jQM muestra un mensaje de error; devolver false desde un manejador le indica a jQM que ya lo has manejado tú.

jquery-mobile
<script>
// Fires when a page is loaded via AJAX into the DOM
$(document).on("pageload", function (e, data) {
  console.log("Loaded: " + data.url);
  console.log("Page obj:", data.page);
});
$(document).on("pageloadfailed", function (e, data) {
  // return false to let jQM show its default error message
  console.log("Failed to load: " + data.url);
});
</script>

Enlazar a eventos de página

Enlaza los eventos de página con delegación de eventos en document, filtrando por el selector #id de la página — esto funciona incluso para páginas obtenidas después vía AJAX. Para navegación programática usa la función 'change' del widget pagecontainer (el reemplazo moderno de $.mobile.changePage), pasando el objetivo y las opciones.

jquery-mobile
<script>
// Delegate by page id — works for AJAX-loaded pages too
$(document).on("pagecreate", "#settings", function () {
  var page = $(this);
  page.find("#save").on("tap", function () {
    alert("Saved settings");
  });
});

// Use the pagecontainer widget (1.4+) for programmatic navigation
$(":mobile-pagecontainer").pagecontainer("change", "#settings", {
  transition: "slide",
  reverse: false
});
</script>

Eliminación y limpieza de páginas

Por defecto jQuery Mobile elimina una página del DOM después de que navegues fuera de ella (salvo que domCache esté activo). pageremove se dispara justo antes de la eliminación — limpia intervalos, listeners o instancias de plugins aquí. El ui.prevPage del evento pagehide da el objeto jQuery de la página recién ocultada para el teardown.

jquery-mobile
<script>
// Fires when a page is removed from the DOM (default behavior for
// non-cached pages after navigation away)
$(document).on("pageremove", function (e, ui) {
  console.log("Page removed from DOM:", ui.prevPage);
});

// Clean up resources when a page is hidden for good
$(document).on("pagehide", "#temp", function () {
  clearInterval($(this).data("timer"));
});
</script>

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.