Carousel

A rotating component for cycling through images or content slides.

Anatomy

Usage

<script>
  import {Carousel} from 'ui-ingredients';
  import {ChevronLeftIcon, ChevronRightIcon} from '$lib/icons';

  let items = [
    'https://images.pexels.com/photos/457882/pexels-photo-457882.jpeg',
    'https://images.pexels.com/photos/189349/pexels-photo-189349.jpeg',
    'https://images.pexels.com/photos/1192671/pexels-photo-1192671.jpeg',
  ];
</script>

<Carousel.Root slideCount={items.length}>
  <Carousel.ItemGroup>
    {#each items as src, index}
      <Carousel.Item {index}>
        <img {src} alt="" />
      </Carousel.Item>
    {/each}
  </Carousel.ItemGroup>

  <Carousel.IndicatorGroup>
    {#each items, index}
      <Carousel.Indicator {index} />
    {/each}
  </Carousel.IndicatorGroup>

  <Carousel.Control>
    <Carousel.PrevTrigger>
      <ChevronLeftIcon />
    </Carousel.PrevTrigger>
    <Carousel.NextTrigger>
      <ChevronRightIcon />
    </Carousel.NextTrigger>
  </Carousel.Control>
</Carousel.Root>

API Reference

Root

Prop	Default	Description
`allowMouseDrag`	`false`	`boolean` Whether to allow scrolling via dragging with mouse
`autoplay`	`false`	`boolean \| { delay: number; }` Whether to scroll automatically. The default delay is 4000ms.
`defaultPage`	`0`	`number` The initial page to scroll to when rendered. Use when you don't need to control the page of the carousel.
`id`		`string` The unique identifier of the machine.
`ids`		`{ root?: string; viewport?: string; item(index: number)?: string; itemGroup?: string; nextTrigger?: string; prevTrigger?: string; indicatorGroup?: string; indicator(index: number?): string; }` The ids of the elements in the carousel. Useful for composition.
`inViewThreshold`	`0.6`	`number \| number[]` The threshold for determining if an item is in view.
`loop`	`false`	`boolean` Whether the carousel should loop around.
`onAutoplayStatusChange`		`(details: AutoplayStatusDetails) => void` Function called when the autoplay status changes.
`onDragStatusChange`		`(details: DragStatusDetails) => void` Function called when the drag status changes.
`onPageChange`		`(details: PageChangeDetails) => void` Function called when the page changes.
`orientation`	`"horizontal"`	`"horizontal" \| "vertical"` The orientation of the element.
`padding`		`string` Defines the extra space added around the scrollable area, enabling nearby items to remain partially in view.
`page`		`number` The controlled page of the carousel.
`slideCount`		`number` The total number of slides. Useful for SSR to render the initial ating the snap points.
`slidesPerMove`	`"auto"`	`number \| "auto"` 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.
`slidesPerPage`	`1`	`number` The number of slides to show at a time.
`snapType`	`"mandatory"`	`"proximity" \| "mandatory"` The snap type of the item.
`spacing`	`"0px"`	`string` The amount of space between items.
`translations`		`IntlTranslations` The localized messages to use.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-orientation`	The orientation of the carousel
`data-part`	root
`data-scope`	carousel

Indicator

Prop	Default	Description
`index`		`number` The index of the indicator.
`readOnly`		`boolean`
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-current`	Present when current
`data-index`	The index of the item
`data-orientation`	The orientation of the indicator
`data-part`	indicator
`data-readonly`	Present when read-only
`data-scope`	carousel

IndicatorGroup

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-orientation`	The orientation of the indicatorgroup
`data-part`	indicator-group
`data-scope`	carousel

Item

Prop	Default	Description
`index`		`number` The index of the item.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-index`	The index of the item
`data-inview`	Present when in viewport
`data-orientation`	The orientation of the item
`data-part`	item
`data-scope`	carousel

ItemGroup

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-dragging`	Present when in the dragging state
`data-orientation`	The orientation of the item
`data-part`	item-group
`data-scope`	carousel

NextTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-orientation`	The orientation of the nexttrigger
`data-part`	next-trigger
`data-scope`	carousel

PrevTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-orientation`	The orientation of the prevtrigger
`data-part`	prev-trigger
`data-scope`	carousel

Viewport

Prop	Default	Description
`asChild`		`Snippet` Render a different element.