Tabs Nuevo

El componente hp-tabs implementa el patrón WAI-ARIA Tabs, permitiendo organizar contenido en pestañas accesibles con navegación por teclado completa y gestión automática de aria-selected.

Demostración

Sin estilos (solo base.css)

Así se ven las tabs usando únicamente @headless-primitives/utils/base.css. La navegación por teclado, aria-selected y la visibilidad de paneles funcionan completamente.

Tab ATab BDisabled

Contenido del panel A.

Contenido del panel B.

Contenido del panel C.

Con estilos personalizados

PerfilAjustesNotificaciones

Gestiona tu información de perfil y datos personales.

Configura las preferencias de tu aplicación.

Controla cómo y cuándo recibes notificaciones.

index.html

<hp-tabs value="tab1" class="tabs">
  <hp-tab-list class="tab-list">
    <hp-tab value="tab1" class="tab">Tab 1</hp-tab>
    <hp-tab value="tab2" class="tab">Tab 2</hp-tab>
    <hp-tab value="tab3" class="tab">Tab 3</hp-tab>
  </hp-tab-list>
  <hp-tab-panel value="tab1" class="panel">
    <p>Contenido del Tab 1</p>
  </hp-tab-panel>
  <hp-tab-panel value="tab2" class="panel">
    <p>Contenido del Tab 2</p>
  </hp-tab-panel>
  <hp-tab-panel value="tab3" class="panel">
    <p>Contenido del Tab 3</p>
  </hp-tab-panel>
</hp-tabs>

style.css

.tab-list {
  display: flex;
  border-bottom: 2px solid #e2e8f0;
}

.tab {
  padding: 10px 20px;
  background: none;
  border: none;
  border-bottom: 2px solid transparent;
  margin-bottom: -2px;
  cursor: pointer;
  font-size: 14px;
  font-weight: 500;
  color: #64748b;
  transition: color 0.2s;
}

.tab:hover {
  color: #1e293b;
}

.tab[aria-selected="true"] {
  color: #3b82f6;
  border-bottom-color: #3b82f6;
}

.tab:focus-visible {
  outline: 2px solid #3b82f6;
  outline-offset: -2px;
  border-radius: 4px;
}

.tab[disabled] {
  opacity: 0.5;
  cursor: not-allowed;
}

.panel {
  padding: 16px;
  border: 1px solid #e2e8f0;
  border-top: none;
  border-radius: 0 0 8px 8px;
}

Instalación

pnpm

pnpm add @headless-primitives/tabs

npm

npm install @headless-primitives/tabs

yarn

yarn add @headless-primitives/tabs

bun

bun add @headless-primitives/tabs

Features

• ⌨️ Navegación completa por teclado (flechas, Home, End).
• ♿️ Roles tablist, tab y tabpanel gestionados automáticamente.
• 🎨 Sin estilos visuales (Headless) — tú decides el diseño.
• ⚡️ Activación por valor (value) para control declarativo y programático.
• 🚫 Soporte para pestañas deshabilitadas individualmente.

Anatomía

<hp-tabs>
  <hp-tab-list>
    <hp-tab></hp-tab>
  </hp-tab-list>
  <hp-tab-panel></hp-tab-panel>
</hp-tabs>

API Reference

hp-tabs

Elemento raíz que coordina el estado entre tabs y panels.

Atributos / Propiedades

Atributo / Propiedad	Tipo	Por Defecto	Descripción
value	string	primera pestaña	Valor de la pestaña activa. Si no se especifica, se activa la primera.

Eventos

Evento	Detalle	Descripción
hp-change	{ value: string }	Se dispara cuando cambia la pestaña activa.

Métodos

Método	Descripción
activateByValue(value)	Activa la pestaña con el valor dado programáticamente.

hp-tab-list

Contenedor de los triggers. Gestiona la navegación por teclado.

Atributos ARIA gestionados automáticamente

• role="tablist" — Asignado automáticamente.

hp-tab

Trigger individual de una pestaña.

Atributos / Propiedades

Atributo / Propiedad	Tipo	Por Defecto	Descripción
value	string	—	Identificador único de la pestaña.
disabled	boolean	false	Deshabilita la pestaña.

Atributos ARIA gestionados automáticamente

• role="tab" — Asignado automáticamente.
• aria-selected — "true" / "false" según estado activo.
• aria-disabled — Sincronizado con disabled.
• tabindex — "0" (activa) / "-1" (inactiva).
• data-state — "selected" / "unselected".

hp-tab-panel

Panel de contenido asociado a una pestaña por value.

Atributos / Propiedades

Atributo / Propiedad	Tipo	Por Defecto	Descripción
value	string	—	Debe coincidir con el value del hp-tab asociado.

Atributos ARIA gestionados automáticamente

• role="tabpanel" — Asignado automáticamente.
• tabindex="0" — Siempre focusable.
• data-state — "selected" / "unselected" (para estilizado CSS).
• aria-hidden — "true" cuando no está seleccionado.
• data-hp-panel — Presente siempre (usado por base.css).

Accesibilidad

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

Navegación por teclado

Tecla	Acción
ArrowLeft / ArrowUp	Pestaña anterior (con wrap circular).
ArrowRight / ArrowDown	Pestaña siguiente (con wrap circular).
Home	Primera pestaña.
End	Última pestaña.
Tab	Sale del tablist al siguiente elemento enfocable.

Ejemplos

Control Programático

const tabs = document.querySelector("hp-tabs");

// Activar una pestaña
tabs.activateByValue("settings");

// Escuchar cambios
tabs.addEventListener("hp-change", (e) => {
  console.log("Pestaña activa:", e.detail.value);
});

Pestaña Deshabilitada

<hp-tabs value="tab1">
  <hp-tab-list>
    <hp-tab value="tab1">Activa</hp-tab>
    <hp-tab value="tab2" disabled>Deshabilitada</hp-tab>
    <hp-tab value="tab3">Otra</hp-tab>
  </hp-tab-list>
  <hp-tab-panel value="tab1"><p>Panel 1</p></hp-tab-panel>
  <hp-tab-panel value="tab2"><p>Panel 2</p></hp-tab-panel>
  <hp-tab-panel value="tab3"><p>Panel 3</p></hp-tab-panel>
</hp-tabs>