Carousel

Cycle through slides with images, text overlays, CTAs, autoplay, touch/swipe, fixed aspect ratios, card framing, and HTMX dynamic loading.

Usage Example

@carousel.Carousel(carousel.Config{
    Slides: []carousel.Slide{
        {ImgSrc: "slide-1.webp", ImgAlt: "Slide 1"},
        {ImgSrc: "slide-2.webp", ImgAlt: "Slide 2"},
    },
})

With Text Overlay

Variant: carousel.WithText adds a gradient title + description overlay per slide.

With Text Overlay

@carousel.Carousel(carousel.Config{
    Variant: carousel.WithText,
    Slides: []carousel.Slide{
        {ImgSrc: "slide-1.webp", ImgAlt: "...", Title: "Front end developers", Description: "The architects of the digital world."},
    },
})

With CTA Button

Variant: carousel.WithCTA adds a call-to-action button using each slide's CTAHref + CTALabel.

With CTA Button

@carousel.Carousel(carousel.Config{
    Variant: carousel.WithCTA,
    Slides: []carousel.Slide{
        {ImgSrc: "slide-1.webp", ImgAlt: "...", Title: "Build faster", Description: "Pre-built UI components.", CTAHref: "#", CTALabel: "Get Started"},
    },
})

With Autoplay

Pass an Autoplay config to advance slides automatically every Interval milliseconds.

With Autoplay

@carousel.Carousel(carousel.Config{
    Variant:  carousel.WithText,
    Autoplay: &carousel.AutoplayConfig{Interval: 4000},
    Slides:   slides,
})

Fixed Aspect Ratio (3:1)

Set AspectRatio (e.g. "3/1") to lock the frame's proportions.

Fixed Aspect Ratio (3:1)

@carousel.Carousel(carousel.Config{
    AspectRatio: "3/1",
    Slides:      slides,
})

With Touch / Swipe

Touch: true enables left/right swipe gestures on touch devices.

With Touch / Swipe

@carousel.Carousel(carousel.Config{
    Touch:  true,
    Slides: slides,
})

On Card

Variant: carousel.OnCard frames the carousel in an article card with product info below.

On Card

@carousel.Carousel(carousel.Config{
    Variant: carousel.OnCard,
    Slides: []carousel.Slide{
        {ImgSrc: "slide-1.webp", ImgAlt: "...", Title: "Abstract Blue Series", Description: "Limited edition print. $49.99"},
    },
})

HTMX Dynamic Loading

Provide an HTMX config and the slides are fetched from the server on page load.

Loading carousel...

HTMX Dynamic Loading

@carousel.Carousel(carousel.Config{
    HTMX: &carousel.HTMXConfig{Get: "/api/components/carousel/slides"},
})

API Reference

Prop	Type	Default	Description
`Slides`	`[]Slide`	`nil`	Slide data (ImgSrc, ImgAlt, Title, Description, CTAHref, CTALabel).
`Variant`	`Variant`	`Default`	Style: "default", "with-text", "with-cta", "on-card".
`Autoplay`	`*AutoplayConfig`	`nil`	Auto-advance config (Interval in ms).
`Touch`	`bool`	`false`	Enable left/right swipe gestures.
`AspectRatio`	`string`	`""`	Lock the frame ratio (e.g. "3/1", "16/9").
`Height`	`string`	`""`	Explicit height override (when AspectRatio is unset).
`HTMX`	`*HTMXConfig`	`nil`	Fetch slides from the server (Get URL).
`ID`	`string`	`auto`	Container id used for Alpine state scoping; auto-generated when empty.
`RootClass`	`string`	`""`	Extra classes on the carousel container.

Card Chat Bubble