---
url: /reference/items/Carousel/js-api.md
---
# JS API
The `Carousel` class extends the [`Indexable` primitive](/reference/items/Indexable/). It inherits its index-navigation methods (`goTo()`, `goNext()`, `goPrev()`), its `boundary` and `reverse` options and its `index` event, so make sure to have a look at [its API reference](/reference/items/Indexable/js-api) too.
A carousel is composed of several components working together:
* `Carousel` — the root component, extending `Indexable`
* `CarouselWrapper` — the scrollable container holding the items
* `CarouselItem` — a single slide
* `CarouselBtn` — a previous, next or go-to control
* `CarouselDrag` — optional pointer-drag behavior, mounted only on fine-pointer devices
## Options
### `axis`
* Type: `'x' | 'y'`
* Default: `'x'`
Defines the scroll direction of the carousel: `'x'` for horizontal, `'y'` for vertical.
```html {2}
...
```
### `boundary`
* Type: `'clamp' | 'loop' | 'bounce'`
* Default: `'clamp'`
Inherited from the [`Indexable`](/reference/items/Indexable/js-api#boundary) primitive, it controls what happens at the ends of the track: `clamp` stops at the first/last item, `loop` wraps around, and `bounce` reverses direction. The `CarouselBtn` controls follow it — `prev`/`next` disable at the ends in `clamp` mode but stay active in `loop` and `bounce`. See the [boundaries example](./examples#boundaries).
```html {3}
...
```
The [`reverse`](/reference/items/Indexable/js-api#reverse) option is also inherited from `Indexable`. The `total` option has no effect here: the carousel derives its length from the number of `CarouselItem` children.
## Getters
### `isHorizontal`
* Type: `boolean`
Whether the carousel scrolls horizontally (the `axis` option is `'x'`).
### `isVertical`
* Type: `boolean`
Whether the carousel scrolls vertically (the `axis` option is `'y'`).
### `items`
* Type: `CarouselItem[]`
The carousel's item components.
### `length`
* Type: `number`
The number of items, used as the `Indexable` length.
### `wrapper`
* Type: `CarouselWrapper`
The scrollable wrapper component.
### `progress`
* Type: `number`
The current scroll progress, between `0` and `1`.
## Methods
### `goTo(indexOrInstruction)`
* Arguments: `number | 'next' | 'previous' | 'first' | 'last' | 'random'`
* Returns: `Promise`
Scroll to the given item. Accepts an index or one of the [`Indexable` instructions](/reference/items/Indexable/js-api). The `goNext()` and `goPrev()` shortcuts are inherited from the primitive.
## Events
### `progress`
Emitted while the carousel scrolls, with the current progress between `0` and `1`. The same value is reflected on the root element through the [`--carousel-progress`](#carousel-progress) custom property.
```js
onCarouselProgress(progress) {
// progress is a number between 0 and 1
}
```
The `index` event is inherited from the [`Indexable` primitive](/reference/items/Indexable/js-api) and emitted whenever the current index changes.
## CSS custom properties
### `--carousel-progress`
Set on the root `Carousel` element, reflects the scroll progress between `0` and `1`.
### `--carousel-item-active`
Set on each `CarouselItem`, equals `1` when the item is the current one and `0` otherwise. Use it to style the active slide.
## CarouselBtn
A control button, delegating to the parent carousel on click.
### `action`
* Type: `'next' | 'prev' | string`
Use `next` or `prev` to step through the items, or a numeric string (e.g. `"2"`) to jump to a specific index. The button disables itself automatically when its action is unavailable, e.g. `prev` on the first item or `next` on the last one.
```html {3}
```
## CarouselDrag
Adds pointer-drag navigation to the wrapper, built with the [`withDrag`](https://js-toolkit.studiometa.dev/api/decorators/withDrag.html) and [`withMountOnMediaQuery`](https://js-toolkit.studiometa.dev/api/decorators/withMountOnMediaQuery.html) decorators. It only mounts on fine-pointer devices (`(pointer: fine)`), leaving native CSS scroll-snap to handle touch devices. Apply it to the same element as `CarouselWrapper`.