Carousel Nuevo

El componente hp-carousel permite mostrar una serie de slides navegables con controles de anterior/siguiente, indicadores (dots) y autoplay opcional. Implementa el patrón WAI-ARIA Carousel.

Demostración

Sin estilos (solo base.css)

Así se ve hp-carousel usando únicamente @headless-primitives/utils/base.css. La navegación, el autoplay y la gestión de estados funcionan completamente sin estilos adicionales.

Slide 1Slide 2Slide 3

Con estilos personalizados

El componente estilizado usando clases CSS y variables de tema.

Slide 1Slide 2Slide 3

←

→

index.html

<hp-carousel loop autoplay interval="3000">
  <hp-carousel-content>
    <hp-carousel-item>Slide 1</hp-carousel-item>
    <hp-carousel-item>Slide 2</hp-carousel-item>
  </hp-carousel-content>
  <hp-carousel-previous>←</hp-carousel-previous>
  <hp-carousel-next>→</hp-carousel-next>
  <hp-carousel-dot index="0"></hp-carousel-dot>
  <hp-carousel-dot index="1"></hp-carousel-dot>
</hp-carousel>

style.css

hp-carousel-item[data-state="inactive"] {
  display: none;
}
hp-carousel-dot[data-state="active"] {
  background: var(--vp-c-brand-1);
}

Instalación

pnpm

pnpm add @headless-primitives/carousel

npm

npm install @headless-primitives/carousel

yarn

yarn add @headless-primitives/carousel

bun

bun add @headless-primitives/carousel

Features

• ⌨️ Soporte completo de navegación por teclado (flechas, Enter, Space).
• ♿️ Accesibilidad WAI-ARIA incorporada (role="region", aria-roledescription).
• 🎨 Sin estilos visuales (Headless) — control total sobre la transición.
• 🔁 Autoplay configurable con intervalos y modo loop circular.
• 📐 Orientación configurable (horizontal / vertical) para sliders complejos.

Anatomía

<hp-carousel>
  <hp-carousel-content>
    <hp-carousel-item></hp-carousel-item>
  </hp-carousel-content>
  <hp-carousel-previous></hp-carousel-previous>
  <hp-carousel-next></hp-carousel-next>
  <hp-carousel-dot index="0"></hp-carousel-dot>
</hp-carousel>

API Reference

hp-carousel

Contenedor raíz del carrusel.

Atributos / Propiedades

Atributo / Propiedad	Tipo	Por Defecto	Descripción
orientation	"horizontal" | "vertical"	"horizontal"	Orientación de la navegación.
loop	boolean	false	Habilita la navegación circular infinita.
autoplay	boolean	false	Activa el avance automático de slides.
interval	number	5000	Tiempo de espera entre slides en ms.
label	string	"Carousel"	Etiqueta accesible para el área del carrusel.

Propiedades

Propiedad	Tipo	Descripción
activeIndex	number	Índice del slide actualmente visible (0-based).

Métodos

Método	Descripción
next()	Avanza al siguiente slide disponible.
previous()	Retrocede al slide anterior disponible.
goTo(index)	Salta directamente al slide con el índice indicado.
start()	Inicia el temporizador de autoplay.
stop()	Detiene el temporizador de autoplay.

Eventos

Evento	Detalle	Descripción
hp-change	{ activeIndex: number }	Se emite cuando el slide activo cambia.

Atributos ARIA gestionados automáticamente

• role="region" — Define el carrusel como una sección significativa de la página.
• aria-roledescription="carousel" — Indica la naturaleza del componente a screen readers.
• aria-label — Sincronizado con la propiedad label.

hp-carousel-content

Wrapper estructural para los slides.

Atributos ARIA gestionados automáticamente

• aria-live="polite" — Anuncia cambios de slide de manera no intrusiva.

hp-carousel-item

Contenedor individual para cada slide.

Atributos ARIA gestionados automáticamente

• role="group" — Identifica el slide dentro del conjunto.
• aria-roledescription="slide" — Describe el elemento como un slide.
• aria-hidden — "true" si el slide no está activo.
• data-state — "active" | "inactive" para estilizado CSS.

hp-carousel-previous / hp-carousel-next

Botones de control para navegar entre slides.

Atributos ARIA gestionados automáticamente

• role="button" — Identifica los elementos como botones accionables.
• aria-label — Etiquetas descriptivas ("Previous slide", "Next slide").
• tabindex="0" — Asegura que sean accesibles mediante el teclado.

hp-carousel-dot

Indicador de paginación individual.

Atributos / Propiedades

Atributo / Propiedad	Tipo	Por Defecto	Descripción
index	number	0	Índice del slide al que apunta.

Atributos ARIA gestionados automáticamente

• role="button" — Identifica el indicador como un botón.
• aria-label — Etiqueta dinámica ("Go to slide N").
• aria-pressed — "true" si es el slide activo actual.
• data-state — "active" | "inactive" para estilizado CSS.

Accesibilidad

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

Navegación por teclado

Tecla	Acción
ArrowRight / ArrowDown	Mueve el foco al siguiente slide (según orientación).
ArrowLeft / ArrowUp	Mueve el foco al slide anterior (según orientación).
Enter / Space	Activa botones de navegación o indicadores de puntos.