# or
yarn add @zag-js/carousel @zag-js/vue
```

## Anatomy

To set up the carousel correctly, you'll need to understand its anatomy and how
we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

First, import the carousel package into your project

```jsx
import * as carousel from "@zag-js/carousel"
```

The carousel package exports two key functions:

- `machine` â The state machine logic for the carousel widget.
- `connect` â The function that translates the machine's state to JSX attributes
  and event handlers.

> You'll also need to provide a unique `id` to the `useMachine` hook. This is
> used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the
carousel machine in your project ð¥

> **Note:** The carousel requires that you provide a `slideCount` property in
> the machine's context. This is the number of slides in the carousel.

```html
<script setup>
  import * as carousel from "@zag-js/carousel"
  import { normalizeProps, useMachine } from "@zag-js/vue"
  import { computed } from "vue"

  const items = [
    "https://tinyurl.com/5b6ka8jd",
    "https://tinyurl.com/7rmccdn5",
    "https://tinyurl.com/59jxz9uu",
  ]

  const service = useMachine(carousel.machine, {
    id: "1",
    slideCount: items.length,
  })

  const api = computed(() => carousel.connect(service, normalizeProps))
</script>

<template>
  <div v-bind="api.getRootProps()">
    <div v-bind="api.getControlProps()">
      <button v-bind="api.getPrevTriggerProps()">Prev</button>
      <button v-bind="api.getNextTriggerProps()">Next</button>
    </div>

    <div v-bind="api.getItemGroupProps()">
      <div
        v-for="(image, index) in items"
        :key="index"
        v-bind="api.getItemProps({ index })"
      >
        <img :src="image" alt="" />
      </div>
    </div>

    <div v-bind="api.getIndicatorGroupProps()">
      <button
        v-for="(_, index) in api.pageSnapPoints"
        :key="index"
        v-bind="api.getIndicatorProps({ index })"
      ></button>
    </div>
  </div>
</template>
```

### Vertical carousel

To create a vertical carousel, set the `orientation` property in the machine's
context to `vertical`.

```jsx {2}
const service = useMachine(carousel.machine, {
  orientation: "vertical",
})
```

### Setting the initial slide

To set the initial slide of the carousel, pass the `defaultPage` property to the
machine's context.

> The `defaultPage` corresponds to the scroll snap position index based on the
> layout. It does not necessarily correspond to the index of the slide in the
> carousel.

```jsx {2}
const service = useMachine(carousel.machine, {
  defaultPage: 2,
})
```

### Setting the number of slides to show at a time

To customize number of slides to show at a time, set the `slidesPerPage`
property in the machine's context. The value must be an integer.

```jsx {2}
const service = useMachine(carousel.machine, {
  slidesPerPage: 2,
})
```

### Setting the number of slides to move at a time

To customize number of slides to move at a time, set the `slidesPerMove`
property in the machine's context. The value must be an integer or `auto`.

```jsx {2}
const service = useMachine(carousel.machine, {
  slidesPerMove: 2,
})
```

**Considerations**

- If the value is `auto`, the carousel will move the number of slides equal to
  the number of slides per page.
- Ensure the `slidesPerMove` is less than or equal to the `slidesPerPage` to
  avoid skipping slides.
- On touch devices, `slidesPerMove` is not enforced during active swiping. The
  browser's native scrolling and CSS Scroll Snap determine slide movement for
  optimal performance and UX.

### Setting the carousel should loop around

To allow looping of slides, set the `loop` property in the machine's context to
`true`.

```jsx {2}
const service = useMachine(carousel.machine, {
  loop: true,
})
```

### Setting the gap between slides

To customize spacing between slides, set the `spacing` property in the machine's
context to a valid CSS unit.

```jsx {2}
const service = useMachine(carousel.machine, {
  spacing: "16px",
})
```

### Listening for page changes

When the carousel page changes, the `onPageChange` callback is invoked.

```jsx {2-5}
const service = useMachine(carousel.machine, {
  onPageChange(details) {
    // details => { page: number }
    console.log("selected page:", details.page)
  },
})
```

### Dragging the carousel

To allow dragging the carousel with the mouse, set the `allowMouseDrag` property
in the machine's context to `true`.

```jsx {2}
const service = useMachine(carousel.machine, {
  allowMouseDrag: true,
})
```

### Autoplaying the carousel

To allow the carousel to autoplay, set the `autoplay` property in the machine's
context to `true`.

```jsx {2}
const service = useMachine(carousel.machine, {
  autoplay: true,
})
```

Alternatively, you can configure the autoplay interval by setting the `delay`
property in the machine's context.

```jsx {2}
const service = useMachine(carousel.machine, {
  autoplay: { delay: 2000 },
})
```

## Styling guide

Earlier, we mentioned that each carousel part has a `data-part` attribute added
to them to select and style them in the DOM.

```css
[data-part="root"] {
  /* styles for the root part */
}

[data-part="item-group"] {
  /* styles for the item-group part */
}

[data-part="item"] {
  /* styles for the root part */
}

[data-part="control"] {
  /* styles for the control part */
}

[data-part="next-trigger"] {
  /* styles for the next-trigger part */
}

[data-part="prev-trigger"] {
  /* styles for the prev-trigger part */
}

[data-part="indicator-group"] {
  /* styles for the indicator-group part */
}

[data-part="indicator"] {
  /* styles for the indicator part */
}

[data-part="autoplay-trigger"] {
  /* styles for the autoplay-trigger part */
}
```

### Active state

When a carousel's indicator is active, a `data-current` attribute is set on the
indicator.

```css
[data-part="indicator"][data-current] {
  /* styles for the indicator's active state */
}
```

## Methods and Properties

The carousel's `api` exposes the following methods and properties:

### Machine Context

The carousel machine exposes the following context properties:

**`ids`**
Type: `Partial<{ root: string; item: (index: number) => string; itemGroup: string; nextTrigger: string; prevTrigger: string; indicatorGroup: string; indicator: (index: number) => string; }>`
Description: The ids of the elements in the carousel. Useful for composition.

**`translations`**
Type: `IntlTranslations`
Description: The localized messages to use.

**`slidesPerPage`**
Type: `number`
Description: The number of slides to show at a time.

**`autoSize`**
Type: `boolean`
Description: Whether to enable variable width slides.

**`slidesPerMove`**
Type: `number | "auto"`
Description: The number of slides to scroll at a time.

When set to `auto`, the number of slides to scroll is determined by the
`slidesPerPage` property.

**`autoplay`**
Type: `boolean | { delay: number; }`
Description: Whether to scroll automatically. The default delay is 4000ms.

**`allowMouseDrag`**
Type: `boolean`
Description: Whether to allow scrolling via dragging with mouse

**`loop`**
Type: `boolean`
Description: Whether the carousel should loop around.

**`page`**
Type: `number`
Description: The controlled page of the carousel.

**`defaultPage`**
Type: `number`
Description: The initial page to scroll to when rendered.
Use when you don't need to control the page of the carousel.

**`spacing`**
Type: `string`
Description: The amount of space between items.

**`padding`**
Type: `string`
Description: Defines the extra space added around the scrollable area,
enabling nearby items to remain partially in view.

**`onPageChange`**
Type: `(details: PageChangeDetails) => void`
Description: Function called when the page changes.

**`inViewThreshold`**
Type: `number | number[]`
Description: The threshold for determining if an item is in view.

**`snapType`**
Type: `"proximity" | "mandatory"`
Description: The snap type of the item.

**`slideCount`**
Type: `number`
Description: The total number of slides.
Useful for SSR to render the initial ating the snap points.

**`onDragStatusChange`**
Type: `(details: DragStatusDetails) => void`
Description: Function called when the drag status changes.

**`onAutoplayStatusChange`**
Type: `(details: AutoplayStatusDetails) => void`
Description: Function called when the autoplay status changes.

**`dir`**
Type: `"ltr" | "rtl"`
Description: The document's text/writing direction.

**`id`**
Type: `string`
Description: The unique identifier of the machine.

**`getRootNode`**
Type: `() => ShadowRoot | Node | Document`
Description: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

**`orientation`**
Type: `"horizontal" | "vertical"`
Description: The orientation of the element.

### Machine API

The carousel `api` exposes the following methods:

**`page`**
Type: `number`
Description: The current index of the carousel

**`pageSnapPoints`**
Type: `number[]`
Description: The current snap points of the carousel

**`isPlaying`**
Type: `boolean`
Description: Whether the carousel is auto playing

**`isDragging`**
Type: `boolean`
Description: Whether the carousel is being dragged. This only works when `draggable` is true.

**`canScrollNext`**
Type: `boolean`
Description: Whether the carousel is can scroll to the next view

**`canScrollPrev`**
Type: `boolean`
Description: Whether the carousel is can scroll to the previous view

**`scrollToIndex`**
Type: `(index: number, instant?: boolean) => void`
Description: Function to scroll to a specific item index

**`scrollTo`**
Type: `(page: number, instant?: boolean) => void`
Description: Function to scroll to a specific page

**`scrollNext`**
Type: `(instant?: boolean) => void`
Description: Function to scroll to the next page

**`scrollPrev`**
Type: `(instant?: boolean) => void`
Description: Function to scroll to the previous page

**`getProgress`**
Type: `() => number`
Description: Returns the current scroll progress as a percentage

**`getProgressText`**
Type: `() => string`
Description: Returns the progress text

**`play`**
Type: `VoidFunction`
Description: Function to start/resume autoplay

**`pause`**
Type: `VoidFunction`
Description: Function to pause autoplay

**`isInView`**
Type: `(index: number) => boolean`
Description: Whether the item is in view

**`refresh`**
Type: `VoidFunction`
Description: Function to re-compute the snap points
and clamp the page

### Data Attributes

**`Root`**

**`data-scope`**: carousel
**`data-part`**: root
**`data-orientation`**: The orientation of the carousel

**`ItemGroup`**

**`data-scope`**: carousel
**`data-part`**: item-group
**`data-orientation`**: The orientation of the item
**`data-dragging`**: Present when in the dragging state

**`Item`**

**`data-scope`**: carousel
**`data-part`**: item
**`data-index`**: The index of the item
**`data-inview`**: Present when in viewport
**`data-orientation`**: The orientation of the item

**`Control`**

**`data-scope`**: carousel
**`data-part`**: control
**`data-orientation`**: The orientation of the control

**`PrevTrigger`**

**`data-scope`**: carousel
**`data-part`**: prev-trigger
**`data-orientation`**: The orientation of the prevtrigger

**`NextTrigger`**

**`data-scope`**: carousel
**`data-part`**: next-trigger
**`data-orientation`**: The orientation of the nexttrigger

**`IndicatorGroup`**

**`data-scope`**: carousel
**`data-part`**: indicator-group
**`data-orientation`**: The orientation of the indicatorgroup

**`Indicator`**

**`data-scope`**: carousel
**`data-part`**: indicator
**`data-orientation`**: The orientation of the indicator
**`data-index`**: The index of the item
**`data-readonly`**: Present when read-only
**`data-current`**: Present when current

**`AutoplayTrigger`**

**`data-scope`**: carousel
**`data-part`**: autoplay-trigger
**`data-orientation`**: The orientation of the autoplaytrigger
**`data-pressed`**: Present when pressed

### CSS Variables

<CssVarTable name="carousel" />
A checkbox allows users to make a binary choice, i.e. a choice between one of
two possible mutually exclusive options.

## Resources


[Latest version: v1.33.1](https://www.npmjs.com/package/@zag-js/checkbox)
[Logic Visualizer](https://zag-visualizer.vercel.app/checkbox)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/checkbox)



**Features**

- Tri-state checkbox. i.e. `indeterminate` state
- Syncs with `disabled` state of fieldset
- Syncs with form `reset` events
- Can be toggled programmatically

## Installation

To use the checkbox machine in your project, run the following command in your
command line:

```bash
npm install @zag-js/checkbox @zag-js/vue