# Carousel

## Overview

A horizontal content slider that lets users navigate through a set of panels or cards one at a time. Built on `embla-carousel-react`. Provides Previous/Next navigation buttons and optional indicator dots.

---

## When to Use

- Image galleries or feature showcases
- Onboarding step walkthroughs
- Product or testimonial carousels
- Mobile-friendly horizontal card stacks

## When NOT to Use

- For multi-column grids that can all be visible at once — use CSS Grid instead.
- Long lists of data — use a `<Table>` or paginated list instead.

---

## Anatomy

```
<Carousel>
  <CarouselContent>
    <CarouselItem>{ /* Card or content */ }</CarouselItem>
    <CarouselItem>{ /* Card or content */ }</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

---

## Examples

### Image / Feature Carousel

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
  Card,
  CardContent,
} from 'xertica-ui/ui';

<Carousel className="w-full max-w-sm mx-auto">
  <CarouselContent>
    {Array.from({ length: 5 }).map((_, i) => (
      <CarouselItem key={i}>
        <Card>
          <CardContent className="flex aspect-square items-center justify-center p-6">
            <span className="text-4xl font-semibold">{i + 1}</span>
          </CardContent>
        </Card>
      </CarouselItem>
    ))}
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>;
```

### Partial-Visible Cards

```tsx
<Carousel>
  <CarouselContent>
    {items.map(item => (
      <CarouselItem key={item.id} className="md:basis-1/2 lg:basis-1/3">
        <Card>
          <CardContent>{item.name}</CardContent>
        </Card>
      </CarouselItem>
    ))}
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

---

## AI Rules

- Set visible card count with `className="md:basis-1/2 lg:basis-1/3"` on `<CarouselItem>` — not by limiting the array.
- `<CarouselPrevious />` and `<CarouselNext />` are positioned absolutely — ensure the parent has `relative` positioning (the `<Carousel>` component handles this).
- Never wrap `<Carousel>` in overflow-hidden containers that might clip the navigation buttons.

---

## Related Components

- [`Card`](./card.md) — Most common Carousel item content