---
title: "Carousel block"
description: "A carousel of image and video uploads with pagination, navigation and thumbnails."
requested_language: sk
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/sk/next/payload/blocks/carousel
version: unreleased (main)
docs_index: https://docs.systhema.app/sk/next/llms.txt
---
> This page isn't translated yet. Showing English.


The Carousel block shows uploads one at a time, with optional pagination, navigation buttons and thumbnails.

![The carousel block fields in the Payload editor](./images/carousel.light.webp)

## Where it is offered

Offered in the `root` and `region` tiers.

## Fields

<!-- generated:block-fields carousel -->

| 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)                                                                                                                 |

<!-- /generated -->

## Rendered output

Renders the [Carousel component](https://docs.systhema.app/sk/next/components/carousel.md) with one `CarouselItem` per upload.

## Converter

`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.

## Customizing

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](https://docs.systhema.app/sk/next/payload/blocks.md#registering-blocks) for the configuration pattern and [Converters](https://docs.systhema.app/sk/next/payload/custom-blocks/converters.md) for the renderer contract. A project converter used in client-mode live preview also needs [browser registration](https://docs.systhema.app/sk/next/payload/frontend/live-preview/client-mode.md).

## Related

- [Carousel component](https://docs.systhema.app/sk/next/components/carousel.md)
- [Gallery block](https://docs.systhema.app/sk/next/payload/blocks/gallery.md)