12/25/2025

Horizontal gallery displaying multiple images

Using a horizontal gallery allows you to display more images more conveniently without worrying about them taking up too much space. in the markdoc

When displaying numerous images, they can consume a significant amount of space. To address this challenge, a horizontal gallery can be utilized.

You can insert shortcodes to generate

{% horizontalGallery 
  images=[
    {src: "image1 Path", alt: "image1 alt"},
    {src: "image2 Path", alt: "image2 alt"}
  ] /%}

How does it work? #

The parent container must have the overflow-visible class.

Add Tags Processor HorizontalGallery.astro

//markdoc.config.mjs
import { defineMarkdocConfig, nodes, component } from "@astrojs/markdoc/config";


export default defineMarkdocConfig({
  tags: {
    horizontalGallery: {
      render: component("./src/components/markdoc/HorizontalGallery.astro"),
      attributes: {
        images: { type: Array, required: true },
      },
    },
  },
...

Add Astro components src\components\markdoc\HorizontalGallery.astro

//src\components\markdoc\HorizontalGallery.astro
---
import AstroImage from "./AstroImage.astro";
interface Props {
  images: {
    src: string;
    alt?: string;
  }[];
}

const { images } = Astro.props;
---

<div class="w-screen max-w-none relative left-1/2 -translate-x-1/2 px-1">
  <div
    class="horizontal-gallery-container flex gap-12 pb-5 overscroll-x-contain overflow-x-auto max-w-5xl mx-auto"
  >
    {
      images.map((image) => (
        <div class={`shrink-0 h-[480px] flex items-center justify-center`}>
          <AstroImage
            src={image.src}
            alt={image.alt || "image"}
            className="max-w-none h-full w-auto object-contain select-none"
          />
        </div>
      ))
    }
  </div>
</div>

<AstroImage /> is a component that automatically optimizes images. watch

Example #