How do I add the Gallery block to a Hugo site?

Add a "block: gallery" entry to the sections list in your page's front matter, then fill in the content fields. HugoBlox renders it automatically — copy the example config above as a starting point.

Is the Gallery block free to use?

Yes. Every HugoBlox block is free and open-source under the MIT license — use it in personal and commercial projects, with no attribution required.

Can I customize the Gallery block?

Yes. It exposes 13 content options, plus 10 design options, and inherits the shared block settings for background, spacing, and colors. You can also describe the changes you want to Hugo Chat AI and it will edit the config for you.

Does the Gallery block work with any Hugo theme?

The block ships in the open-source HugoBlox kit. Add the kit to any Hugo site and the block becomes available in your page sections — there is no theme lock-in.

hugoblox.com/blocks/gallery

MediaFree · MITPreact · interactive

Gallery block

An image gallery with grid and masonry layouts, click-to-zoom lightbox, and lazy-loaded placeholders.

Customize with AI View source

Add it to any Hugo page's sections list — no build step.

v1.0.0Version

13Options

MITLicense

Quick start

Add the Gallery block

Drop this into your page's front matter, under the sections list. Edit the values, and HugoBlox renders the block — no build step.

Add to your page's sections

- block: gallery
  content:
    title: Lab tour
    subtitle: Highlights from the 2026 retreat — full set in our [archive](/photos/).
    items:
      - src: media/albums/lab-2024/01.jpg
        caption: The **main workspace** where most of our research happens
        credit: "Photo: [Jane Doe](https://janedoe.com)"
      - src: media/albums/lab-2024/02.jpg
        title: Annual retreat
        caption: "*Edinburgh, 2024* — three days of deep work and walks"
        link: /news/retreat-2024/
  design:
    layout: grid
    columns: 4
    gap: md
    aspect_ratio: square
    caption_position: below
    hover_zoom: true
    lightbox: true

Flexibility

Layouts & variants

Switch the block's design with these presets — no custom CSS.

layoutLayout style. Grid produces uniform tiles; masonry packs variable-height images; justified row-balances images Flickr-style; carousel is a horizontal scroll-snap strip; slideshow shows one image at a time with optional autoplay.

griddefaultmasonryjustifiedcarouselslideshow

gapSpacing between tiles.

smmddefaultlg

aspect_ratioTile aspect ratio. Applies to grid, carousel, and slideshow layouts. Masonry uses each image's natural aspect ratio; justified packs rows by natural ratio at the configured row height.

squaredefaultlandscapeportraitwide

caption_positionWhere captions appear on each tile.

belowdefaultoverlayhovernone

Reference

Configuration

Every option the Gallery block accepts, generated from its schema.

Content options

Properties set under the block's content key.

Property	Type	Default	Description
`title`	`string`	—	Section heading shown above the gallery (supports inline Markdown bold/italic).
`subtitle`	`string`	—	Supporting sentence below the title — context, dates, or photographer credit line.
`items`	`object[]`	—	Curated list of images. Use when you want explicit ordering and per-image captions/credits. For drop-in folder use, prefer the album field instead.
`items[].src`required	`string`	—	Image source. Either a path under assets/ (e.g. 'media/photos/keynote.jpg' or 'albums/lab-2024/01.jpg'), or a remote URL (https://…). Page-bundle resources can also be referenced by filename if the gallery sits inside a page bundle.
`items[].title`	`string`	—	Short headline shown above the caption (lightbox + below-caption layouts). Supports inline Markdown.
`items[].caption`	`string`	—	Image caption shown in the lightbox and (depending on layout) beside or over the tile. Supports inline Markdown — bold, italic, inline code, and links all work. Setting caption here overrides any caption coming from a sidecar file or embedded EXIF/IPTC tags on this image.
`items[].alt`	`string`	—	Plain-text alternative for screen readers and search engines. Defaults to the plainified caption (or humanised filename if no caption). Override when the visual content of the image differs from its caption.
`items[].credit`	`string`	—	Photo credit line shown in the lightbox footer. Supports inline Markdown — perfect for `Photo: [Name](https://photographer-site.com)`.
`items[].link`	`string`	—	Optional URL — adds an 'Open page →' link in the lightbox footer that navigates to this page. Useful when each image represents a project, talk, or publication with its own detail page.
`album`	`string`	—	Folder path (relative to assets/) to auto-load images from. All image files (.jpg/.png/.webp/.gif/.avif/.svg) in the folder are picked up and sorted by filename. Captions, titles, credits, and links can be supplied per image via a sidecar file next to each image — `<image>.jpg.yaml` (Lightroom-style) or `<image>.yaml` (clean) — without listing every image in items[]. JPEGs with embedded IPTC/EXIF tags (from Lightroom/Capture One exports) are also picked up automatically.
`page_resources`	`boolean`	false	Auto-discover image resources attached to the current page bundle. Useful for blog posts and project pages where photos live next to index.md — drop them in and they appear as a gallery. Sidecar files inside the bundle are resolved the same way as for album mode.
`sort`	`asc \| desc`	asc	Sort order applied to album-loaded images (ignored when using items[], which preserves the explicit order).
`limit`	`integer`	0	Maximum number of images to display. Useful for capping an album to the most recent N. Set to 0 (default) for no limit.

Design options

Properties set under the block's design key — shared background, spacing, and color settings apply on top.

Property	Type	Default	Description
`layout`	`grid \| masonry \| justified \| carousel \| slideshow`	grid	Layout style. Grid produces uniform tiles; masonry packs variable-height images; justified row-balances images Flickr-style; carousel is a horizontal scroll-snap strip; slideshow shows one image at a time with optional autoplay.
`columns`	`integer`	3	Number of columns at the widest breakpoint. Scales down responsively. For grid/masonry: number of stacked columns. For carousel: number of items visible at desktop width (mobile always shows ~1 with the next peeking). Ignored for justified and slideshow.
`row_height`	`integer`	240	Target row height in pixels — justified layout only. Each row is rendered at this height; widths within the row are derived from each image's aspect ratio.
`autoplay`	`boolean`	false	Slideshow layout only — auto-advance to the next slide on an interval. Pauses on hover and resets when the user manually navigates.
`autoplay_interval`	`integer`	5000	Milliseconds between slides when autoplay is enabled. Clamped to a minimum of 1000ms.
`gap`	`sm \| md \| lg`	md	Spacing between tiles.
`aspect_ratio`	`square \| landscape \| portrait \| wide`	square	Tile aspect ratio. Applies to grid, carousel, and slideshow layouts. Masonry uses each image's natural aspect ratio; justified packs rows by natural ratio at the configured row height.
`caption_position`	`below \| overlay \| hover \| none`	below	Where captions appear on each tile.
`hover_zoom`	`boolean`	true	Subtle scale-up on hover for grid tiles. Adds a tactile, interactive feel.
`lightbox`	`boolean`	true	Open a full-viewport lightbox on click, with keyboard navigation (← → Esc) and touch swipe. Disable to make tiles either inert or link-only (when items[].link is set).

Compose

Works well with

Blocks that pair naturally with Gallery on the same page.

CTA Card Team Showcase Testimonials

Frequently asked

Gallery block FAQ

Add a "block: gallery" entry to the sections list in your page's front matter, then fill in the content fields. HugoBlox renders it automatically — copy the example config above as a starting point.

Ready to build with the Gallery block?

Customize with AI View source