--- title: "Carousel" description: "Slides that drag, swipe and snap with momentum, on Embla Carousel: item sizes, spacing, vertical orientation, options and plugins." url: "https://susonwaiba.github.io/htmx-ui/docs/components/carousel" section: "Components" --- # Carousel Slides that drag, swipe and snap with momentum, on Embla Carousel: item sizes, spacing, vertical orientation, options and plugins. ```html
1
2
3
4
5
``` ## Installation The carousel runs on [Embla Carousel](https://www.embla-carousel.com), a dependency of htmx-ui that is loaded only on pages with a carousel. Plugins are separate packages; add the ones you use: ```bash bun bun add embla-carousel-autoplay ``` ```bash npm npm install embla-carousel-autoplay ``` ```bash pnpm pnpm add embla-carousel-autoplay ``` ```bash yarn yarn add embla-carousel-autoplay ``` ## Markup - `.carousel[data-carousel]` holds a `.carousel-viewport` (it clips), a `.carousel-container` (it moves) and the `.carousel-item`s. - `[data-carousel-prev]` and `[data-carousel-next]` buttons scroll, and disable themselves at the ends. Give them an `aria-label`, and [`.btn-no-press`](https://susonwaiba.github.io/htmx-ui/docs/components/button#press) so they don't nudge when pressed. - The behaviour marks the carousel as a region and each item as a slide ("2 of 5"); name the region with `aria-label`. `←` `→` scroll when focus is inside it. - Without JavaScript the slides are a clipped row; give the viewport `overflow-x-auto` if they must stay reachable then. ## Item size Items fill the viewport. Size them with `basis-*` utilities on the items (responsive ones too), or `--carousel-size` on the carousel for all of them. ```html
1
2
3
4
5
6
``` ## Spacing `--carousel-gap` on the carousel sets the space between items (1rem by default). It is padding on each item, so Embla's snap points stay exact. ```html
1
2
3
4
5
6
7
8
``` ## Orientation `data-orientation="vertical"` scrolls up and down (Embla's `axis: "y"`); give the viewport a height. The buttons move above and below and turn, and `↑` `↓` scroll. ```html
1
2
3
4
5
``` ## Options `data-carousel-options` takes [Embla's options](https://www.embla-carousel.com/api/options/) as JSON and passes them on: `loop`, `align`, `dragFree`, `slidesToScroll`, `startIndex`, `breakpoints` and the rest. Below: a loop that starts on the third slide. `.carousel-controls` puts the buttons in a row underneath, with an empty `[data-carousel-dots]` that fills with a dot per snap point. ```html
1
2
3
4
5
``` ## Plugins Register an Embla plugin under a name once, in your entry script, then ask for it by that name with its options in `data-carousel-plugins`: ```ts app.ts import Autoplay from "embla-carousel-autoplay"; import { initComponents, registerCarouselPlugin } from "htmx-ui"; registerCarouselPlugin("autoplay", Autoplay); // before initComponents() ``` ```html
1
2
3
4
5
``` ## API For anything else, take [Embla's API](https://www.embla-carousel.com/api/) from the element once it has loaded: ```ts import { getCarousel } from "htmx-ui"; const el = document.querySelector("#gallery")!; el.addEventListener("carousel:init", (e) => { const api = (e as CustomEvent).detail.api; // same as getCarousel(el) api.scrollTo(3); }); el.addEventListener("carousel:select", (e) => console.log("slide", (e as CustomEvent).detail.index)); ``` ## With htmx A carousel swapped in by htmx initialises like any component. To add slides to one already running, swap them into its `.carousel-container`: Embla notices new slides and re-measures, and the dots and labels follow. ## Reference | Class | Description | | --- | --- | | `.carousel` | The carousel; sets --carousel-gap (1rem) and --carousel-size (100%). | | `.carousel-viewport` | Clips the slides; give it a height when vertical. | | `.carousel-container` | The moving row (column when vertical). | | `.carousel-item` | A slide; basis-* utilities set its size. | | `.carousel-prev / .carousel-next` | Buttons beside the slides (above and below when vertical). | | `.carousel-controls` | A row under the slides for buttons and dots. | | `.carousel-dots / .carousel-dot` | Dot buttons, built in an empty [data-carousel-dots]. | | `[data-carousel]` | Behaviour: starts Embla, buttons, dots, keys, labels. | | `[data-orientation="vertical"]` | Scroll vertically (axis "y"). | | `[data-carousel-options]` | Embla options as JSON. | | `[data-carousel-plugins]` | Plugins by registered name, with their options, as JSON. | | `registerCarouselPlugin(name, factory)` | Make an Embla plugin available by name. | | `getCarousel(el)` | The Embla API of a carousel (after carousel:init). | | `carousel:init / carousel:select` | Events: ready (detail.api), slide changed (detail.index). |