--- url: /reference/items/Carousel.md --- # Carousel The `Carousel` component displays a set of items in a scrollable track. It is built on the [`Indexable` primitive](/reference/items/Indexable/) and relies on native CSS scroll-snap on touch devices, keeping the JavaScript minimal. Pointer drag is added on top for fine-pointer devices (mouse, trackpad) through the optional [`CarouselDrag`](./js-api#carouseldrag) component. It works horizontally or vertically, exposes the full `Indexable` navigation API (`goTo()`, `goNext()`, `goPrev()`) and emits a `progress` event alongside a `--carousel-progress` CSS custom property you can hook animations onto. ## Table of content * [Examples](./examples.md) * [JS API](./js-api.md) ## Usage A carousel is authored from a few nested components: * a root `Carousel` element; * a `CarouselWrapper` holding the track, which is also the scroll container — add `CarouselDrag` on the same element to enable pointer dragging; * one `CarouselItem` per slide; * optional `CarouselBtn` controls to move to the previous, next or a specific item. ::: code-group ```js twoslash [app.js] import { registerComponent } from '@studiometa/js-toolkit'; import { Carousel } from '@studiometa/ui'; registerComponent(Carousel); ``` ```twig [carousel.twig]
{% for item in 1..4 %}
#{{ item }}
{% endfor %}
``` ::: ### Vertical carousel Set the [`axis`](./js-api#axis) option to `y` to scroll vertically instead of horizontally: ```twig
...
```