Skip to main content

Overview

The Carousel plugin creates slideshow-style content blocks with multiple items. Each item has a heading and content area. Perfect for image galleries, testimonials, or multi-step presentations.

Installation

npm install @yoopta/carousel

Basic Usage

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 Slides: Create carousel with multiple slides/items
  • Navigation: Previous/Next navigation controls
  • Structured Content: Each slide has heading and content areas
  • Keyboard Support: Full keyboard navigation
  • Shortcuts: Type carousel to insert

Structure

The Carousel block consists of nested elements:
carousel-container
└── carousel-list
    └── carousel-list-item (multiple, props: order)
        ├── carousel-list-item-heading
        └── carousel-list-item-content

Configuration

import Carousel from '@yoopta/carousel';

const plugins = [Carousel];

Options

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

Element Props

Commands

Carousel commands are available via CarouselCommands.

insertCarousel

Insert a new Carousel block.
import Carousel, { CarouselCommands } from '@yoopta/carousel';

CarouselCommands.insertCarousel(editor, {
  items: 3,
  at: 0,
  focus: true,
});
items
number
default:"1"
Number of carousel items to create initially
at
YooptaPathIndex
Index where to insert the block
focus
boolean
Whether to focus the new block after insert

buildCarouselElements

Build carousel element structure (used internally).
import { CarouselCommands } from '@yoopta/carousel';

const carouselElement = CarouselCommands.buildCarouselElements(editor, {
  items: 3,
});

deleteCarousel

Delete a carousel block.
import { CarouselCommands } from '@yoopta/carousel';

CarouselCommands.deleteCarousel(editor, blockId);

Block Operations

You can also use the generic Blocks API:
import { Blocks } from '@yoopta/editor';

// Delete
Blocks.deleteBlock(editor, { blockId });

// Update block meta
Blocks.updateBlock(editor, { blockId, meta: { align: 'center' } });

Element Operations

Use the Elements API to manipulate carousel items:
import { Elements } from '@yoopta/editor';

// Insert new carousel item
Elements.insertElement(editor, {
  blockId,
  type: 'carousel-list-item',
  props: { order: 3 },
  at: 'next',
  focus: true,
});

// Update item order
Elements.updateElement(editor, {
  blockId,
  type: 'carousel-list-item',
  props: { order: 2 },
  path: itemPath,
});

// Delete carousel item
Elements.deleteElement(editor, {
  blockId,
  type: 'carousel-list-item',
  path: itemPath,
});

Keyboard Behavior

  • Enter in heading: moves focus to content area
  • Enter in content: inserts a new carousel item after the current one
  • Backspace in empty heading: removes the item (or deletes the block if it’s the only item)
  • Arrow Left/Right: Navigate between carousel items

Usage Examples

// Each carousel item can contain images in the content area
CarouselCommands.insertCarousel(editor, {
  items: 5, // 5 slides for gallery
  at: 0,
});

// Then add images to each carousel-list-item-content

Testimonials

// Use carousel for rotating testimonials
CarouselCommands.insertCarousel(editor, {
  items: 3,
  at: 0,
});

// Heading: Customer name
// Content: Testimonial text

Product Showcase

// Showcase multiple products in a carousel
CarouselCommands.insertCarousel(editor, {
  items: 4,
  at: 0,
});

// Heading: Product name
// Content: Product description and images

Parsers

HTML

  • Deserialize: <div> with carousel structure and data attributes
  • Serialize: Carousel block → <div> with list of items, each with heading and content

Email

  • Serialize: Table-based layout showing all carousel items stacked (since email clients don’t support interactive carousels)

Styling

The carousel plugin provides the structure, but you’ll typically want to add custom styling for:
  • Navigation buttons (previous/next)
  • Indicators/dots
  • Transitions between slides
  • Responsive behavior
/* Example custom styles */
.carousel-container {
  position: relative;
  overflow: hidden;
}

.carousel-list {
  display: flex;
  transition: transform 0.3s ease;
}

.carousel-list-item {
  min-width: 100%;
  padding: 20px;
}
  • Image — Image blocks
  • Steps — Step-by-step instructions
  • Tabs — Tabbed content
  • Accordion — Collapsible sections

Build docs developers (and LLMs) love