Carousel block
A carousel of image and video uploads with pagination, navigation and thumbnails.
On this page
The Carousel block shows uploads one at a time, with optional pagination, navigation buttons and thumbnails.
Where it is offeredLink to this section
Offered in the root and region tiers.
FieldsLink to this section
| Field | Type | Label | Default | Notes |
|---|---|---|---|---|
_tier | select | Options: root (Root), region (Region), fragment (Fragment), slot (Slot), stack (Stack) | ||
aspectRatio | select | Aspect Ratio | 3/2 | Required; Options: 21/9-md (21:9 on desktop, 4:3 on mobile), 21/9 (cinema - 21:9), 16/9 (video - 16:9), 4/3 (landscape photo - 4:3), 3/2 (landscape photo - 3:2), 1/1 (square - 1:1), 3/4 (portrait photo - 3:4), 4/5 (instagram - 4:5), 9/16 (vertical video - 9:16) |
items | upload | Carousel Items | Required; Related to uploads; Multiple values | |
loop | checkbox | Loop the carousel | false | |
message | ui | |||
navigation | radio | Navigation | wrapper | Required; Shown when siblingData?.width!=="screen"; Options: none (None), wrapper (On the images), bottom (After the images) |
objectFit | radio | Object Fit | cover | Required; Shown when siblingData?.aspectRatio!=="auto"; Options: cover (Cover), contain (Fit) |
objectPositionX | radio | Horizontal Alignment | center | Shown when siblingData?.aspectRatio!=="auto"; Required; Options: left (Left), center (Center), right (Right) |
objectPositionY | radio | Vertical Alignment | center | Shown when siblingData?.aspectRatio!=="auto"; Required; Options: top (Top), center (Center), bottom (Bottom) |
pagination | radio | Pagination | wrapper | Required; Shown when siblingData?.width!=="screen"; Options: none (None), wrapper (Bullets), bottom (Numbers) |
thumbs | checkbox | Enable thumbnails | false | Shown when siblingData?.width!=="screen" |
width | radio | Width alignment | default | Required; Shown when (hasValue?hasValue(siblingData):true)&&siblingData?._tier!=="fragment"; Options: default (Default), container (Container), screen (Screen) |
Rendered outputLink to this section
Renders the Carousel component with one CarouselItem per upload.
ConverterLink to this section
carouselConverter maps populated items uploads to <CarouselItem>. Images use <Image>; videos use muted, autoplaying <Video> elements. Upload IDs and unsupported MIME types render no slide content. The converter forwards pagination, navigation, thumbnail and loop settings. If you register it at fragment tier, it omits the width prop.
CustomizingLink to this section
Import CarouselBlock from @systhemaui/payload/blocks as the starting schema for a project block. Register the definition and your renderer through customBlocks, using type: 'block' and the editor tiers you intend to support. A distinct slug creates a new block; a converter registered under the existing carousel slug takes precedence over the built-in converter. Keep the fields that renderer reads, including populated relationships and nested editor states.
See Registering blocks for the configuration pattern and Converters for the renderer contract. A project converter used in client-mode live preview also needs browser registration.