Carousel

The Mishka Chelekom Headless Carousel is a Phoenix function component that turns a set of slides into a scroll-snap carousel for LiveView. The scrolling is the browser's own: the viewport is a scroll container and the slides are its snap points, so dragging, trackpads, touch and momentum scrolling behave the way people expect, and the slides still scroll if the script is missing. A small HeadlessCarousel hook adds what CSS cannot report: which slide is current, previous and next buttons, indicator buttons and autoplay.

The root is a region with aria-roledescription="carousel", and each slide is a group labelled "1 of 4" unless you give it a label. The current slide is found by measuring the scroll position once scrolling settles, so a swipe that lands two slides along is still reported correctly. State is on the markup as data-index, data-current, data-orientation and data-snap. Style the parts with class, viewport_class, slide_class, controls_class, control_class, indicators_class and indicator_class.

The component needs a unique id, which carries the hook. label is required: it names the carousel for assistive technology, and the indicator group is named after it ("Panels slides" in the examples).

snap (start, center, end or none) and orientation (horizontal or vertical) are written to data-snap and data-orientation on the root, so your CSS can react to them. orientation also decides which arrow keys move the carousel (Up and Down when vertical) and which scroll axis the hook measures. The snapping itself comes from your classes.

index sets which slide is marked current when the carousel renders, counting from 0. loop makes the previous and next buttons wrap around at the ends instead of being disabled there. autoplay takes a number of milliseconds and moves to the next slide on that interval, going back to the first slide after the last. It pauses while the pointer is over the carousel or focus is inside it, and it does not run for visitors who prefer reduced motion.

show_controls renders the previous and next buttons, named by previous_label and next_label ("Previous slide" and "Next slide" by default). show_indicators renders one button per slide, named "Go to slide 2" and so on.

on_change is the name of a LiveView event. The hook pushes it with %{"index" => 2} when it starts and each time the current slide changes.

Each :slide entry takes a label to replace the default "1 of 4" description, and a class. The optional :controls slot is drawn at the start of the controls row, before the built-in buttons, for custom markup.

Each part carries a stable data-part and a structural chelekom-carousel__* class you can target.

Follows the WAI-ARIA Carousel pattern. Tab reaches the viewport and the buttons. With the viewport focused, Left and Right move one slide (Up and Down in a vertical carousel), and Home and End jump to the first and last slide. Only the current slide is exposed to assistive technology. Autoplay pauses on hover and focus, and the viewport gets aria-live="off" while it runs so screen readers are not interrupted. For visitors who prefer reduced motion, autoplay stays off and the buttons jump to a slide instead of scrolling smoothly.