Saltar al contenido

Combobox

Un <input> editable con autocompletado (patrón APG combobox): se tipea para filtrar la lista y se elige una opción o, con data-ts-allow-custom en la raíz, se deja un valor libre. A diferencia del Select, el campo de texto es el control.

Formularios · TaishoDS Core, en HTML plano.

Ejemplos

Un ejemplo por caso, funcionando. Cada ejemplo es el HTML de su vista previa: se copia tal cual y, con el CSS y el JS del Core cargados, se ve y funciona igual.

Buscar un miembro del equipo

html

Limpiable con valor

html

Solo lectura

html

Densidad compacta, con error

html

Con ícono de búsqueda

html

Opciones agrupadas por rol

html

Búsqueda en el servidor, cargando

html

Dentro de un popover de filtros

html

Con ayuda, ícono y descripción

html

Varios responsables

Ana Torres Carla Ruiz
html

Referencia de clases

Todos los valores de cada modificador, con su HTML listo para copiar.

Tamaño

El alto del campo: sm, md o lg.

html

Variante

El color del borde según validación: default, success, warning, info o danger.

html

Densidad

El aire interno del campo: comfortable o compact.

html

Estados

is-loading muestra el Spinner en el campo y el Cargando… del panel (aria-busy); no bloquea la edición. is-readonly la impide pero mantiene el campo enfocable.

html

Combinaciones

Tamaño y variante actuando juntos.

html

Cuándo usarlo

  • La lista es larga y filtrar tipeando es la forma natural de llegar a la opción.
  • El usuario podría necesitar un valor que no está en la lista (data-ts-allow-custom).
  • Autocompletar mientras escribe ahorra más que abrir un panel y recorrerlo.
  • Hay que asignar varios valores de una lista larga o que viene del servidor, y conviene verlos en el campo (data-ts-multiple).

Cuándo no

  • La lista es corta y conocida: abrir y elegir alcanza → select.
  • Hace falta un buscador dentro del panel, o resumir varias opciones en un contador → select.
  • No se captura un valor sino que se ejecutan comandos de toda la app → command-palette.

Cómo usarlo

  • Conviene mostrar un estado vacío claro cuando el filtro no encuentra nada.
  • Si se permiten valores libres, debe quedar obvio cómo se confirma uno nuevo.

Cómo no usarlo

  • No se usa para cuatro opciones: el input mete más fricción que un Select para tan poco.
  • No se esconden opciones importantes detrás del filtro sin un default visible.

TaishoDS Core

Necesita el JS del Core: maneja foco, teclado y estado.

Es un campo de texto libre con filtrado en vivo y una lista de opciones.

El Core lo engancha por estos atributos. Van en el marcado; no hace falta inicializar nada.

  • data-ts-async
  • data-ts-clear
  • data-ts-combobox
  • data-ts-dismiss
  • data-ts-dismissible
  • data-ts-listbox
  • data-ts-listbox-empty
  • data-ts-listbox-input
  • data-ts-listbox-live
  • data-ts-listbox-loading
  • data-ts-listbox-panel
  • data-ts-listbox-spinner
  • data-ts-listbox-tag-template
  • data-ts-listbox-tags
  • data-ts-listbox-template
  • data-ts-listbox-toggle
  • data-ts-listbox-value
  • data-ts-multiple
  • data-ts-placeholder
  • data-ts-value

Qué hace: Patrón combobox de la APG sobre la lista de Select, más el filtrado mientras se tipea. Escape con el panel abierto no sigue hacia un Popover que lo contenga, y pasar el mouse sobre una opción la activa. Los grupos (role="group" con aria-labelledby) se filtran ocultando el encabezado del que queda vacío.

Atributo Qué hace
data-ts-allow-customEn la raíz: adopta como valor el texto que no está en la lista.
data-ts-listbox-toggleEl chevron como botón.
data-ts-clearBotón de limpiar.
readonlyEn el input, como en cualquier campo.
density-compact, ts combobox-prefix-blockDensidad compacta y prefijo: marcado y CSS.
data-select-option-icon, data-select-option-descriptionOpciones con ícono y descripción: marcado estático. El campo muestra sólo la etiqueta.
setComboboxLoading(root, true | false)Pone is-loading, aria-busy, el Spinner y «Cargando…».
data-ts-asyncEn la raíz: el Core no filtra en el cliente (el servidor ya filtró); tu app escucha ts:change y lee query.
form.reset()Vuelve al valor inicial.

Sin build, desde el CDN: taisho.combobox.css, además de taisho.base.css. También se carga:

  • taisho.button.css
  • taisho.checkbox.css
  • taisho.icon.css
  • taisho.spinner.css
  • taisho.tag.css
  • taisho.visually-hidden.css

Para el funcionamiento general del Core, ver Comportamiento.

Accesibilidad

Implementa el patrón Combobox de la WAI-ARIA APG.

  • El input es role="combobox" con aria-autocomplete="list", aria-expanded y aria-controls al listbox.
  • Navegación: flechas para moverse por las opciones, Enter para elegir la enfocada (o confirmar el texto), Escape para revertir y cerrar.
  • aria-activedescendant apunta a la opción resaltada, anunciada por el lector sin sacar el foco del input. Pasar el mouse sobre una opción la resalta (y la deja como activa).
  • Las opciones con descripción se nombran por su etiqueta (aria-labelledby) y se describen con aria-describedby; el ícono es decorativo (aria-hidden). El campo muestra sólo la etiqueta.
  • El chevron es un <button tabindex="-1" aria-label="Mostrar opciones"> (data-ts-listbox-toggle en el Core): abre o cierra con el mouse o el toque y no entra en el orden de Tab, porque el teclado ya tiene el input y las flechas. El mouse no le saca el foco al input.
  • El botón de limpiar (data-ts-clear) entra en el orden de Tab justo después del input, tiene aria-label propio y sólo se ve con valor, sin disabled y sin readonly. Al activarlo se vacía el valor y el foco queda en el input.
  • readonly no abre el panel ni con el mouse ni con las flechas: el input queda enfocable y seleccionable, sin chevron ni botón de limpiar.
  • Con el panel abierto, Escape lo cierra y no sigue hacia un Popover o un Modal que contenga al Combobox; con el panel cerrado, Escape llega al contenedor. form.reset() devuelve el valor inicial sin disparar el evento de cambio.
  • Las opciones con group van dentro de un role="group" nombrado por su encabezado (aria-labelledby). Las flechas recorren las opciones en el orden en que se ven, saltando de un grupo al siguiente; los encabezados no son opciones y no reciben foco. Al filtrar, el grupo que queda sin opciones desaparece con su encabezado.
  • Para el modo async, se llama a setComboboxLoading(root, true|false): pone is-loading y aria-busy="true" en el input y en el panel, y un Spinner role="status" en el campo: ése es el único anuncio, para no repetir «Cargando» dos veces. En el panel, el «Cargando…» es texto visible con el Spinner decorativo: un listbox no admite hijos con role="status". Mientras carga no se muestra «Sin resultados», porque sería falso. No deshabilita el input: se puede seguir escribiendo.
  • El prefijo es decorativo (ícono o avatar) y queda fuera del orden de Tab; el nombre accesible del input sigue siendo su label. La densidad (density-compact o density-comfortable) sólo cambia el tamaño: no toca ningún atributo ARIA.
  • Con multiple (data-ts-multiple en el Core), el listbox lleva aria-multiselectable="true" y cada opción su aria-selected; la casilla es decorativa (aria-hidden). Las altas y las bajas se anuncian por una región aria-live="polite", porque el foco no se mueve al elegir. El botón de cada etiqueta se nombra con el valor que quita. Al quitar una etiqueta con el teclado, el foco pasa a la vecina y, si no queda ninguna, al input. required bloquea el envío sólo mientras no hay valores. form.reset() vuelve a la selección inicial.

Teclado

Además de lo que ya hace el navegador (Tab mueve el foco, Enter activa un botón).

Tecla Qué hace
↑↓Recorre las opciones filtradas.
EnterElige la opción enfocada, o confirma el texto escrito.
EscapeRevierte al valor anterior y cierra.
Enter(múltiple)Agrega o quita la opción enfocada sin cerrar el panel. Sin opción enfocada, agrega lo escrito si coincide con una opción o si se admiten valores libres.
Backspace(múltiple)Con el campo vacío, quita la última etiqueta. Con texto, borra texto.
Tab(múltiple)Recorre los botones para quitar cada etiqueta, antes de llegar al campo.

Verificación

Qué se probó de verdad. Lo que no se probó lo dice: preferimos un «sin verificar» a una afirmación de más.

  • axe WCAG 2.2 A + AA en navegador real, en tema claro y oscuro, antes de cada versión.
  • teclado Mapa de teclas documentado arriba, contrastado contra el componente.
  • lector de pantalla Sin verificar con lector de pantalla. Conviene probarlo en la combinación de componentes propia, no sólo aquí, donde cada uno aparece solo y en su estado feliz.