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 title in UI menus
description
string
default: "Create carousel/slider"
Description shown in menus
shortcuts
string[]
default: "['carousel']"
Keyboard shortcuts to trigger the plugin in slash menu
Element Props
Item order/index in the carousel (0-indexed)
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 ,
});
Number of carousel items to create initially
Index where to insert the block
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
Image Gallery
// 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.3 s ease ;
}
.carousel-list-item {
min-width : 100 % ;
padding : 20 px ;
}