Back to site

Image Carousel

Displays images in a carousel with a thumbnail strip for navigation.

Overview #

An image carousel with a large main image and a synchronized thumbnail strip for navigation. Supports looping, arrow controls, and configurable aspect ratios.

Properties #

label string

Optional label for the carousel to help identify it in the editor.

images array | default: array

Array of images to display in the carousel.

Item Properties:

source string

Image source.

alt string

Alt text describing the image.

positionVertical enum | default: center

Vertical positioning of the image within the frame.

Accepted values:
  • top
  • center
  • bottom

positionHorizontal enum | default: center

Horizontal positioning of the image within the frame.

Accepted values:
  • left
  • center
  • right

showArrows boolean | default: true

Show previous and next arrow buttons.

loop boolean | default: true

Loop the carousel back to the beginning when reaching the end.

aspectRatio enum | default: landscape

Aspect ratio for the main image display.

Accepted values:
  • none
  • square
  • landscape
  • portrait
  • widescreen
  • horizontal-strip

sizes string | default: (max-width: 1280px) 100vw, 1280px

Sizes attribute for main images (e.g. "(max-width: 1280px) 100vw, 1280px").

widths array | default: array

Widths to generate for responsive main images (e.g. 640, 1280, 2560).

Examples #

Aspect ratios #

Quiet Street
Sunset
Castle
Dunedin Cliff 
---
import ImageCarousel from "@wrappers/image-carousel/ImageCarousel.astro";
---

<ImageCarousel
aspectRatio="square" images={
  [
    {
      "source": "/src/assets/images/component-docs/quiet-street.jpg",
      "alt": "Quiet Street"
    },
    {
      "source": "/src/assets/images/component-docs/sunset.jpg",
      "alt": "Sunset"
    },
    {
      "source": "/src/assets/images/component-docs/castle.jpg",
      "alt": "Castle"
    },
    {
      "source": "/src/assets/images/component-docs/dunedin-cliff.jpg",
      "alt": "Dunedin Cliff"
    }
  ]
} loop showArrows
/>
---
blocks:
  _component: building-blocks/wrappers/image-carousel
  images:
    - source: /src/assets/images/component-docs/quiet-street.jpg
      alt: Quiet Street
    - source: /src/assets/images/component-docs/sunset.jpg
      alt: Sunset
    - source: /src/assets/images/component-docs/castle.jpg
      alt: Castle
    - source: /src/assets/images/component-docs/dunedin-cliff.jpg
      alt: Dunedin Cliff
  showArrows: true
  loop: true
  aspectRatio: square
---
Quiet Street
Sunset
Castle
Dunedin Cliff 
---
import ImageCarousel from "@wrappers/image-carousel/ImageCarousel.astro";
---

<ImageCarousel
aspectRatio="portrait" images={
  [
    {
      "source": "/src/assets/images/component-docs/quiet-street.jpg",
      "alt": "Quiet Street"
    },
    {
      "source": "/src/assets/images/component-docs/sunset.jpg",
      "alt": "Sunset"
    },
    {
      "source": "/src/assets/images/component-docs/castle.jpg",
      "alt": "Castle"
    },
    {
      "source": "/src/assets/images/component-docs/dunedin-cliff.jpg",
      "alt": "Dunedin Cliff"
    }
  ]
} loop showArrows
/>
---
blocks:
  _component: building-blocks/wrappers/image-carousel
  images:
    - source: /src/assets/images/component-docs/quiet-street.jpg
      alt: Quiet Street
    - source: /src/assets/images/component-docs/sunset.jpg
      alt: Sunset
    - source: /src/assets/images/component-docs/castle.jpg
      alt: Castle
    - source: /src/assets/images/component-docs/dunedin-cliff.jpg
      alt: Dunedin Cliff
  showArrows: true
  loop: true
  aspectRatio: portrait
---