Docs
Carousel
Posted on August 14, 2024 (Last modified on June 7, 2025) • 5 min read • 953 wordsUse the carousel shortcode to display a carousel of several images.
Overview
Use the carousel
shortcode to display a carousel of several images, with similar behavior as the
Image. As an example, the following shortcode displays a centered carousel with three slides, 16x9 aspect ratio, and a relative width of 67% on large screens.
{{< carousel ratio="16x9" class="col-sm-12 col-lg-8 mx-auto" >}}
{{< img src="img/coffee.jpg" caption="slide 1" >}}
{{< img src="img/phone.jpg" caption="slide 2" >}}
{{< img src="img/dunes.jpg" caption="slide 3" >}}
{{< /carousel >}}
Arguments
The carousel shortcode supports the following arguments:
Name | Type | Required | Default | Comment |
---|---|---|---|---|
class | string | Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. | ||
id | string | Unique identifier of the current element. | ||
portrait | bool | v0.18.3 Flag to adjust the image ratio from landscape to portrait. The image itself is not rotated, only the crop area is adjusted. Not applicable to vector graphics. | ||
ratio | select | Ratio of the media asset. When the asset is an image, it is resized and cropped (not applicable to vector graphics). For video assets, the padding of the embedded frame is adjusted. Supported values: [1x1 , 3x2 , 4x3 , 16x9 , 21x9 ]. |
Name | Type | Required | Default |
---|---|---|---|
class | string | ||
Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. | |||
id | string | ||
Unique identifier of the current element. | |||
portrait | bool | ||
v0.18.3 Flag to adjust the image ratio from landscape to portrait. The image itself is not rotated, only the crop area is adjusted. Not applicable to vector graphics. | |||
ratio | select | ||
Ratio of the media asset. When the asset is an image, it is resized and cropped (not applicable to vector graphics). For video assets, the padding of the embedded frame is adjusted. Supported values: [1x1 , 3x2 , 4x3 , 16x9 , 21x9 ]. |
Add an inner img
element for each slide of the carousel. The img
element supports the following arguments:
Name | Type | Required | Default | Comment |
---|---|---|---|---|
active | bool | Sets the current item as active (only one item at a time). By default, the first item is made active. | ||
caption | string | Caption of the carousel slide or illustration. | ||
loading | select | eager |
Image loading behavior. The loading of lazily loaded images is deferred until the image is within scrolling range of the viewport. This should reduce the initial loading time of the website. It is recommended to lazily load only those images that are below the page fold. Supported values: [lazy , eager ]. |
|
src | string, template.URL | yes | Path or url of the image, e.g. img/example.jpg . Images with multiple color modes are expected to have a basename that ends with either -dark or -light . |
Name | Type | Required | Default |
---|---|---|---|
active | bool | ||
Sets the current item as active (only one item at a time). By default, the first item is made active. | |||
caption | string | ||
Caption of the carousel slide or illustration. | |||
loading | select | eager |
|
Image loading behavior. The loading of lazily loaded images is deferred until the image is within scrolling range of the viewport. This should reduce the initial loading time of the website. It is recommended to lazily load only those images that are below the page fold. Supported values: [lazy , eager ]. |
|||
src | string, template.URL | yes | |
Path or url of the image, e.g. img/example.jpg . Images with multiple color modes are expected to have a basename that ends with either -dark or -light . |
Examples
Change the ratio and orientation of your carousel with shortcode arguments.
1x1 Ratio
Set the ratio
to 1x1
for a square aspect ratio.
{{< carousel id="carousel-1x1" ratio="1x1" class="col-sm-12 col-lg-6 mx-auto" >}}
{{< img src="img/coffee.jpg" caption="slide 1" >}}
{{< img src="img/phone.jpg" caption="slide 2" >}}
{{< img src="img/dunes.jpg" caption="slide 3" >}}
{{< /carousel >}}
Set the ratio
to 3x2
for a landscape aspect ratio.
{{< carousel id="carousel-3x2" ratio="3x2" class="col-sm-12 col-lg-8 mx-auto" >}}
{{< img src="img/coffee.jpg" caption="slide 1" >}}
{{< img src="img/phone.jpg" caption="slide 2" >}}
{{< img src="img/dunes.jpg" caption="slide 3" >}}
{{< /carousel >}}
4x3 Ratio
Set the ratio
to 4x3
for a landscape aspect ratio.
{{< carousel id="carousel-4x3" ratio="4x3" class="col-sm-12 col-lg-8 mx-auto" >}}
{{< img src="img/coffee.jpg" caption="slide 1" >}}
{{< img src="img/phone.jpg" caption="slide 2" >}}
{{< img src="img/dunes.jpg" caption="slide 3" >}}
{{< /carousel >}}
16x9 Ratio
Set the ratio
to 16x9
for a landscape aspect ratio.
{{< carousel id="carousel-16x9" ratio="16x9" class="col-sm-12 col-lg-8 mx-auto" >}}
{{< img src="img/coffee.jpg" caption="slide 1" >}}
{{< img src="img/phone.jpg" caption="slide 2" >}}
{{< img src="img/dunes.jpg" caption="slide 3" >}}
{{< /carousel >}}
21x9 Ratio
Set the ratio
to 21x9
for a landscape aspect ratio.
{{< carousel id="carousel-21x9" ratio="21x9" class="col-sm-12 col-lg-8 mx-auto" >}}
{{< img src="img/coffee.jpg" caption="slide 1" >}}
{{< img src="img/phone.jpg" caption="slide 2" >}}
{{< img src="img/dunes.jpg" caption="slide 3" >}}
{{< /carousel >}}
Original Aspect Ratio
Important
The carousel does not crop the images when omitting the aspect ratio. Instead, the images keep their original aspect ratio. Ensure the images have an equal aspect ratio to avoid layout shifting.
Omit the ratio
to keep the original aspect ratio.
{{< carousel id="carousel-original" class="col-sm-12 col-lg-8 mx-auto" >}}
{{< img src="img/coffee.jpg" caption="slide 1" >}}
{{< img src="img/coffee.jpg" caption="slide 2" >}}
{{< img src="img/coffee.jpg" caption="slide 3" >}}
{{< /carousel >}}
Set portrait
to true
for a portrait aspect ratio.
{{< carousel id="carousel-portrait-3x2" ratio="3x2" portrait="true" class="col-sm-8 col-lg-6 mx-auto" >}}
{{< img src="img/coffee.jpg" caption="slide 1" >}}
{{< img src="img/phone.jpg" caption="slide 2" >}}
{{< img src="img/dunes.jpg" caption="slide 3" >}}
{{< /carousel >}}