> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yoopta.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Carousel

> Display images or content in a carousel/slider format

export const PluginPlayground = ({pluginSlug, height = 420}) => {
  const baseUrl = 'https://yoopta.dev';
  return <div className="not-prose my-6 rounded-xl border border-zinc-200 dark:border-zinc-800 overflow-hidden">
      <iframe title={`${pluginSlug} plugin demo`} src={`${baseUrl}/playground/plugin/${pluginSlug}`} className="w-full border-0 bg-white dark:bg-zinc-900" style={{
    height: typeof height === 'number' ? `${height}px` : height
  }} />
    </div>;
};

## Overview

The Carousel plugin allows you to create interactive carousels to display images or content in a slider format. It's perfect for showcasing multiple items in a compact, scrollable interface.

<PluginPlayground pluginSlug="carousel" height={320} />

## Installation

```bash theme={null}
npm install @yoopta/carousel
```

## Basic Usage

Pass the plugin to `createYooptaEditor`; do not pass `plugins` to `<YooptaEditor>`.

```jsx theme={null}
import { useMemo } from 'react';
import YooptaEditor, { createYooptaEditor } from '@yoopta/editor';
import Carousel from '@yoopta/carousel';

const plugins = [Carousel];

export default function Editor() {
  const editor = useMemo(() => createYooptaEditor({ plugins, marks: [] }), []);
  return <YooptaEditor editor={editor} onChange={() => {}} />;
}
```

## Features

* **Multiple Items**: Display multiple carousel items
* **Keyboard Shortcuts**: Type `carousel` to insert
* **Responsive**: Adapts to different screen sizes
* **Customizable**: Extend with custom rendering

## Structure

The Carousel plugin consists of nested elements:

```
carousel-container
└── carousel-list-item (multiple)
    ├── content
    └── ...
```

## Commands

### buildCarouselElements

Creates the initial carousel structure.

```typescript theme={null}
CarouselCommands.buildCarouselElements(editor, { items: 5 });
```

<ParamField path="items" type="number">
  Number of carousel items to create (default: 5)
</ParamField>

## Extending the Plugin

### Custom Rendering

```jsx theme={null}
import { CarouselPlugin } from '@yoopta/carousel';

const CustomCarousel = CarouselPlugin.extend({
  elements: {
    'carousel-container': {
      render: (props) => (
        <div className="my-carousel-container" {...props.attributes}>
          {props.children}
        </div>
      ),
    },
    'carousel-list-item': {
      render: (props) => (
        <div className="my-carousel-item" {...props.attributes}>
          {props.children}
        </div>
      ),
    },
  },
});
```

### Integration with Embla Carousel

For advanced carousel functionality, you can integrate with [Embla Carousel](https://www.embla-carousel.com/):

```jsx theme={null}
import { CarouselPlugin } from '@yoopta/carousel';
import useEmblaCarousel from 'embla-carousel-react';

const CustomCarousel = CarouselPlugin.extend({
  elements: {
    'carousel-container': {
      render: (props) => {
        const [emblaRef] = useEmblaCarousel({ loop: true });
        
        return (
          <div ref={emblaRef} {...props.attributes}>
            <div className="embla__viewport">
              {props.children}
            </div>
          </div>
        );
      },
    },
  },
});
```

## Options

<ResponseField name="display" type="object">
  <Expandable title="properties">
    <ResponseField name="title" type="string" default="Carousel">
      Display title in UI
    </ResponseField>

    <ResponseField name="description" type="string">
      Description shown in menus
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shortcuts" type="string[]" default="['carousel']">
  Keyboard shortcuts to trigger the plugin
</ResponseField>

## Use Cases

<CardGroup cols={2}>
  <Card title="Image Gallery">
    Display multiple images in a scrollable carousel
  </Card>

  <Card title="Product Showcase">
    Show product features or variations
  </Card>

  <Card title="Testimonials">
    Rotate through customer testimonials
  </Card>

  <Card title="Portfolio">
    Showcase portfolio items or projects
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Optimize Images">
    Ensure images are optimized for web to maintain carousel performance
  </Accordion>

  <Accordion title="Limit Items">
    Keep carousel items reasonable (5-10) for better UX
  </Accordion>

  <Accordion title="Add Navigation">
    Provide clear navigation controls for users
  </Accordion>
</AccordionGroup>

## Related Plugins

* [Image Plugin](/plugins/image) - For individual images
* [Tabs Plugin](/plugins/tabs) - For tabbed content organization