Select Nuevo

El componente hp-select implementa el patrón WAI-ARIA Select-only Combobox, con popup anchored, navegación completa por teclado, roving tabindex y soporte nativo de formularios HTML.

Demostración

Sin estilos (solo base.css)

AppleBananaCherry

Con estilos personalizados

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

index.html

<hp-select name="fruit" placeholder="Elige una fruta">
  <hp-select-trigger>
    <hp-select-value></hp-select-value>
    <span aria-hidden="true">▼</span>
  </hp-select-trigger>
  <hp-select-content>
    <hp-select-item value="apple">Manzana</hp-select-item>
    <hp-select-item value="banana">Plátano</hp-select-item>
    <hp-select-item value="date" disabled>Dátil</hp-select-item>
  </hp-select-content>
</hp-select>

style.css

hp-select-trigger {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 0.5rem 1rem;
  border: 1px solid #e5e7eb;
  border-radius: 6px;
  cursor: pointer;
}

hp-select-trigger[aria-expanded="true"] {
  border-color: #3b82f6;
  box-shadow: 0 0 0 1px #3b82f6;
}

hp-select-content[data-state="closed"] {
  display: none;
}

hp-select-item[aria-selected="true"] {
  background: #eff6ff;
  color: #3b82f6;
  font-weight: 500;
}

hp-select-item[aria-disabled="true"] {
  opacity: 0.5;
  cursor: not-allowed;
}

Instalación

pnpm

pnpm add @headless-primitives/select

npm

npm install @headless-primitives/select

yarn

yarn add @headless-primitives/select

bun

bun add @headless-primitives/select

Features

• ⌨️ Navegación completa: flechas, Home, End, Escape, Enter/Space.
• ♿️ role="combobox", role="listbox", role="option", aria-expanded y aria-selected automáticos.
• 🎨 Sin estilos visuales (Headless) — posicionamiento computado automático.
• 📋 Integración con formularios HTML via <input type="hidden"> generado.
• 🔒 Items deshabilitados individualmente.

Anatomía

<hp-select>
  <hp-select-trigger>
    <hp-select-value></hp-select-value>
  </hp-select-trigger>
  <hp-select-content>
    <hp-select-item value="option-1"></hp-select-item>
    <hp-select-item value="option-2"></hp-select-item>
  </hp-select-content>
</hp-select>

API Reference

hp-select

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

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 select.
name	string	""	Nombre para integración con formularios.
placeholder	string	""	Texto cuando no hay selección.
required	boolean	false	Campo requerido en formularios.

Métodos

Método	Descripción
openSelect(edge?)	Abre el select. edge: "first" | "last".
close()	Cierra el select y devuelve foco al trigger.
toggle()	Alterna abierto/cerrado.
select(value)	Selecciona un item por valor.
clear()	Limpia la selección (value = null).

Eventos

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

hp-select-trigger

Botón que abre/cierra el popup.

Atributos ARIA gestionados automáticamente

• role="combobox" — Siempre presente.
• aria-expanded — "true" | "false".
• aria-disabled — Sincronizado con disabled.
• aria-controls — ID del content.
• aria-activedescendant — ID del item activo.
• tabindex="0" — Siempre focusable.

hp-select-value

Muestra el texto del valor seleccionado o placeholder.

hp-select-content

Popup listbox con los items.

Atributos ARIA gestionados automáticamente

• role="listbox" — Siempre presente.
• data-state — "open" | "closed".
• aria-hidden — Sincronizado con estado.

hp-select-item

Opción individual.

Atributos / Propiedades

Atributo / Propiedad	Tipo	Por Defecto	Descripción
value	string	""	Identificador único del item.
disabled	boolean	false	Deshabilita el item.

Atributos ARIA gestionados automáticamente

• role="option" — Siempre presente.
• aria-selected — "true" | "false".
• aria-disabled — Sincronizado con disabled.

Accesibilidad

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

Navegación por teclado

Tecla	Acción
Enter / Space	Abre el select (trigger) o selecciona el item activo (content).
ArrowDown	Abre y mueve al primer item (trigger) o siguiente item (content).
ArrowUp	Abre y mueve al último item (trigger) o anterior item (content).
Home	Mueve al primer item habilitado.
End	Mueve al último item habilitado.
Escape	Cierra el popup y devuelve foco al trigger.