Combobox Nuevo

El componente hp-combobox implementa el patrón WAI-ARIA Combobox con filtrado en tiempo real, popup anchored y navegación completa por teclado.

Demostración

Sin estilos (solo base.css)

Así se ve hp-combobox usando únicamente @headless-primitives/utils/base.css. El filtrado, la navegación por teclado y la gestión de estados funcionan completamente sin estilos adicionales.

AppleBananaCherry

Con estilos personalizados

El componente estilizado usando clases CSS y variables de tema.

🍎 Apple🍌 Banana🍒 Cherry📅 Date (deshabilitado)🫐 Elderberry

index.html

<hp-combobox placeholder="Busca...">
  <hp-combobox-input>
    <input type="text" placeholder="Escribe aquí..." />
  </hp-combobox-input>
  <hp-combobox-content class="my-content">
    <hp-combobox-option value="apple">Apple</hp-combobox-option>
    <hp-combobox-option value="banana">Banana</hp-combobox-option>
  </hp-combobox-content>
</hp-combobox>

style.css

hp-combobox-content[data-state="closed"] {
  display: none;
}
hp-combobox-option[data-state="hidden"] {
  display: none;
}
hp-combobox-option[aria-selected="true"] {
  background: var(--vp-c-brand-soft);
  color: var(--vp-c-brand-1);
}
hp-combobox-option[aria-disabled="true"] {
  opacity: 0.5;
  cursor: not-allowed;
}

Instalación

pnpm

pnpm add @headless-primitives/combobox

npm

npm install @headless-primitives/combobox

yarn

yarn add @headless-primitives/combobox

bun

bun add @headless-primitives/combobox

Features

• ⌨️ Soporte completo de navegación por teclado (flechas, Enter, Escape, Home, End).
• ♿️ Accesibilidad WAI-ARIA incorporada (role="combobox", aria-autocomplete, aria-activedescendant).
• 🎨 Sin estilos visuales (Headless) — posicionamiento computado automático.
• 🔍 Filtrado en tiempo real basado en el input del usuario.
• 🔒 Soporte para opciones deshabilitadas y estados de carga.

Anatomía

<hp-combobox>
  <hp-combobox-input>
    <input type="text" />
  </hp-combobox-input>
  <hp-combobox-content>
    <hp-combobox-option value="opt1"></hp-combobox-option>
    <hp-combobox-option value="opt2"></hp-combobox-option>
  </hp-combobox-content>
</hp-combobox>

API Reference

hp-combobox

Contenedor raíz con filtrado y gestión de estado.

Atributos / Propiedades

Atributo / Propiedad	Tipo	Por Defecto	Descripción
value	string | null	null	Valor seleccionado.
open	boolean	false	Estado abierto/cerrado.
disabled	boolean	false	Deshabilita el combobox.
placeholder	string	""	Placeholder del input.

Métodos

Método	Descripción
openCombobox(edge?)	Abre el popup. edge: "first" | "last".
close()	Cierra el popup y devuelve foco al input.
toggle()	Alterna abierto/cerrado.
select(value)	Selecciona una opción por valor.
clear()	Limpia la selección y el input.

Eventos

Evento	Detalle	Descripción
hp-change	{ value, label, item }	Cuando se selecciona una opción.
hp-highlight	{ value, label, item }	Cuando se destaca una opción con teclado.
hp-open	—	Cuando el popup se abre.
hp-close	—	Cuando el popup se cierra.

hp-combobox-input

Wrapper del input nativo. Gestiona la vinculación ARIA con el listbox.

Atributos ARIA gestionados automáticamente (en el <input> interno)

• role="combobox" — Identifica el elemento como un combobox.
• aria-expanded — Sincronizado con el estado abierto/cerrado.
• aria-autocomplete="list" — Indica que el combobox ofrece una lista de sugerencias.
• aria-controls — Vincula el input con el hp-combobox-content.
• aria-activedescendant — ID de la opción actualmente destacada.

hp-combobox-content

Popup listbox que contiene las opciones filtrables.

Atributos ARIA gestionados automáticamente

• role="listbox" — Identifica el contenedor como una lista de opciones.
• data-state — "open" | "closed" para estilizado CSS.
• aria-hidden — Sincronizado con la visibilidad.

hp-combobox-option

Opción individual dentro del listbox.

Atributos / Propiedades

Atributo / Propiedad	Tipo	Por Defecto	Descripción
value	string	""	Identificador único de la opción.
disabled	boolean	false	Deshabilita la opción.

Atributos ARIA gestionados automáticamente

• role="option" — Identifica el elemento como una opción de lista.
• aria-selected — Sincronizado con el estado de selección.
• aria-disabled — Refleja el estado deshabilitado.
• data-state — "visible" | "hidden" basado en el filtrado.

Accesibilidad

Adhiere al patrón WAI-ARIA APG para Combobox.

Navegación por teclado

Tecla	Acción
ArrowDown	Abre el popup o mueve el foco a la siguiente opción.
ArrowUp	Abre el popup o mueve el foco a la opción anterior.
Home	Mueve el foco a la primera opción.
End	Mueve el foco a la última opción.
Enter	Selecciona la opción destacada y cierra el popup.
Escape	Cierra el popup y devuelve el foco al input.
Cualquier texto	Filtra las opciones disponibles en el listbox.