Skip to main content

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.

Installation

npm install @yoopta/carousel

Basic Usage

import { CarouselPlugin } from '@yoopta/carousel';

const plugins = [
  CarouselPlugin,
  // ... other plugins
];

<YooptaEditor
  editor={editor}
  plugins={plugins}
/>

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.
CarouselCommands.buildCarouselElements(editor, { items: 5 });
items
number
Number of carousel items to create (default: 5)

Extending the Plugin

Custom Rendering

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>
      ),
    },
  },
});
For advanced carousel functionality, you can integrate with Embla Carousel:
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

display
object
shortcuts
string[]
default:"['carousel']"
Keyboard shortcuts to trigger the plugin

Use Cases

Image Gallery

Display multiple images in a scrollable carousel

Product Showcase

Show product features or variations

Testimonials

Rotate through customer testimonials

Portfolio

Showcase portfolio items or projects

Best Practices

Ensure images are optimized for web to maintain carousel performance
Keep carousel items reasonable (5-10) for better UX
Provide clear navigation controls for users