📖 Referencia de TypeScript, Presets & API v0.15.0

Documentación de Parámetros y API

Name: astro-swiper-zosei
Author: Zosei

Configura carruseles completos en Astro pasando props directamente a <Sw />, usando preset="..." o probándolos en el Playground interactivo.

✨ Novedad v0.15.0

¿Prefieres construirlo visualmente?

Usa nuestro constructor interactivo para ajustar efectos, velocidades, colores y generar código Astro en 1 clic.

Abrir Playground

Instalación Oficial (Astro 5+ & 7+ Ready)

1. Integración automática con Astro CLI:

npx astro add astro-swiper-zosei

2. O con tu gestor de paquetes favorito:

pnpm add astro-swiper-zosei swiper

Sistema de Presets Listos para Producción (`preset="..."`)

Configuraciones de 1 línea optimizadas para casos de uso comunes.

preset="hero"

Hero Banner

Fade suave, autoplay con pausa al hover, loop infinito y controles glass.

preset="cards"

3D Cards

Efecto de tarjetas tridimensionales apiladas con sombras y rotación suave.

preset="marquee"

Logo Marquee

Desplazamiento infinito continuo sin pausas para marcas y patrocinadores.

preset="testimonials"

Testimonials

Slides centrados y responsivos (1 a 3 columnas) con paginación dinámica.

preset="gallery"

Gallery Zoom

Galería interactiva con soporte de zoom gestual y paginación por fracción.

Parámetros del Componente <Sw />

Todas las propiedades son tipadas e inferidas automáticamente por TypeScript.

Propiedad	Tipo TypeScript	Por Defecto	Descripción
preset	'hero' \| 'cards' \| 'marquee' \| 'testimonials' \| 'gallery'	undefined	⚡ Preset predeterminado de 1 sola línea optimizado para producción.
direction	'horizontal' \| 'vertical'	'horizontal'	Dirección del desplazamiento de los slides.
slidesPerView	number \| 'auto'	1	Cantidad de diapositivas visibles simultáneamente en el viewport.
spaceBetween	number	0	Espacio en píxeles de separación (gap) entre cada diapositiva.
loop	boolean	false	Activa el ciclo infinito continuo donde el último slide enlaza con el primero.
rewind	boolean	false	Regresa al primer slide al llegar al final del carrusel.
speed	number	300	Duración de la animación de transición en milisegundos.
effect	'slide' \| 'fade' \| 'cube' \| 'coverflow' \| 'flip' \| 'cards' \| 'creative'	'slide'	Efecto de transición visual tridimensional o plano.
autoplay	boolean \| AutoplayOptions	false	Configura reproducción automática con delay, pauseOnMouseEnter, disableOnInteraction, etc.
pauseWhenHidden	boolean	false	Pausa el autoplay con Intersection Observer automáticamente cuando el carrusel no está visible en pantalla.
lazyInit	boolean	false	Inicializa la instancia de Swiper solo cuando el carrusel entra al viewport del navegador.
navigation	boolean \| NavigationOptions	false	Habilita botones anterior/siguiente de navegación.
pagination	boolean \| PaginationOptions	false	Habilita paginación (bullets clicables, números de fracción o barra de progreso).
scrollbar	boolean \| ScrollbarOptions	false	Habilita barra de desplazamiento interactiva y arrastrable.
breakpoints	Record<number, SwiperOptions>	undefined	Configuración responsiva adaptativa según el ancho de pantalla en píxeles.
grabCursor	boolean	false	Muestra cursor de agarre interactivo (grab / grabbing) al pasar el ratón.
centeredSlides	boolean	false	Centra el slide activo en el medio del contenedor.
autoHeight	boolean	false	Ajusta la altura del carrusel dinámicamente según la altura del slide activo.
freeMode	boolean \| FreeModeOptions	false	Permite arrastre libre e inercial sin ajuste forzado a bordes de slides.
keyboard	boolean \| KeyboardOptions	false	Habilita navegación mediante las teclas de flecha del teclado físico.
mousewheel	boolean \| MousewheelOptions	false	Habilita navegación mediante la rueda de desplazamiento del ratón o touchpad.
zoom	boolean \| ZoomOptions	false	Habilita zoom interactivo mediante doble clic o gesto táctil de pellizco.
grid	{ rows: number, fill?: "row" \| "column" }	undefined	Disposición en cuadrícula matricial multi-fila 2D.
thumbs	string \| { swiper?: string \| Swiper }	undefined	Selector del carrusel de miniaturas sincronizado (ej: "#my-thumbs" o ".my-thumbs").
options	AstroSwiperOptions	{}	Objeto de configuración de bajo nivel de Swiper.js para casos avanzados.
addDefaultClass	boolean	true	Añade automáticamente la clase CSS requerida ".swiper" al contenedor principal.
useCustomElement	boolean	true	Utiliza el custom element web component <astro-swiper-zosei>.

Subcomponentes & Micro-Controles v0.15.0

Componentes modulares estilizados con Tailwind CSS v4 para navegación, paginación, contadores y controles interactivos.

Sw / Sw.Container / Swiper<Sw>

Contenedor principal con gestión de ciclo de vida, soporte de Presets, View Transitions y configuración declarativa.

Props: preset, direction, slidesPerView, spaceBetween, loop, effect, autoplay, navigation, pagination, scrollbar, ...

Sw.Wrap / Sw.Wrapper / Wrapper<Sw.Wrap>

Contenedor flex obligatorio de los slides con soporte de fallback Zero-JS con CSS Scroll-Snap.

Props: class, id, ...HTMLAttributes<"div">

Sw.Slide / Sw.S / Slide<Sw.Slide>

Diapositiva individual para alojar imágenes, tarjetas, contenido HTML o componentes Astro.

Props: class, lazy, ...HTMLAttributes<"div">

Sw.Prev / Sw.Next<Sw.Prev /> / <Sw.Next />

Botones modernos de navegación con iconos SVG nítidos y variantes de Tailwind v4.

Sw.Pag / Sw.Pagination<Sw.Pag />

Indicador de paginación por bullets, números de fracción o barra de progreso.

Sw.Scroll / Sw.Scrollbar<Sw.Scroll />

Barra de desplazamiento arrastrable personalizada con soporte gestual.

Props: color, class

Sw.Toggle / Sw.AutoplayToggle<Sw.Toggle />

Control interactivo de Play / Pausa con estado animado SVG para carruseles con autoplay.

Props: variant, size, position ("top-right" | "bottom-right" | "top-left" | "bottom-left" | "none")

Sw.Count / Sw.Counter<Sw.Count />

Badge numérico en tiempo real del slide activo ("01 / 08").

Props: padZero (true/false), separator (" / "), variant, size, position

Sw.Full / Sw.Fullscreen<Sw.Full />

Botón nativo para expandir el carrusel a pantalla completa.

Props: variant, size, position

Sw.Lazy / Sw.LazyPreloader<Sw.Lazy />

Spinner SVG animado para carga diferida (lazy load) de imágenes.