Image gallery
Show several images as a gallery or carousel, with optional previews.
Code name: Gallery · Category: Media
Registered in the live renderer. Website context and the limitations below still apply.
When to use it
Use a gallery to show a portfolio, project details or a collection of relevant photographs. Choose images that help visitors understand your work.
In the editor
- Add images with descriptive alt text.
- Choose a gallery layout.
- Test navigation, image previews and mobile cropping.
Example
This example uses illustrative content. Media placeholders must be replaced with your own assets; data-backed blocks need the normal website context.
<Gallery data={[{ id: 1, src: "/defaults/image_placeholder.svg", alt: "Replace with a description of your project", previewUrl: "" }]} />Behaviour and limitations
- Items use id, src, alt and previewUrl inside data.
- listGroup and carouselGroup are editor headings, not content properties to populate.
- Preserve image sources when changing only captions or layout.
Content model
Edit gallery images and their alt text inside data. Preserve src unless the user asks to change the image.
Property reference
Types below describe the editor controls and known choices, not every value accepted by the renderer. A renderer default is extracted from its parameter; an editor-only default does not prove the runtime default. “Not declared here” does not mean required. Preserve omitted values unless the requested edit needs them.
| Property | Editor value type | Default evidence | Guidance |
|---|---|---|---|
data | array | [{"id":1,"src":"/defaults/image_placeholder.svg","alt":"Example image description","previewUrl":""},{"id":2,"src":"/defaults/image_placeholder_vertical.svg","alt":"Example image description","previewUrl":""},{"id":3,"src":"/defaults/image_placeholder_vertical.svg","alt":"Example image description","previewUrl":""},{"id":4,"src":"/defaults/image_placeholder.svg","alt":"Example image description","previewUrl":""}] (renderer) | Images List. See the usage notes for this block. |
galleryVariant | "masonry", "standard", "woven" | "masonry" (renderer) | Gallery variant. See the usage notes for this block. |
columnsGallery | number | 2 (renderer) | Columns. See the usage notes for this block. |
listGroup | See guidance | Not declared here | Editor group heading only. Do not emit this as content. |
carouselGroup | See guidance | Not declared here | Editor group heading only. Do not emit this as content. |
previewVariant | "dots", "thumbnail", "none" | "thumbnail" (renderer) | Preview variant. See the usage notes for this block. |
imageType | "responsive", "contain" | "responsive" (renderer) | Image Size. See the usage notes for this block. |
galleryType | "list", "carousel" | "list" (renderer) | Gallery Type. See the usage notes for this block. |
thumbnailPosition | "vertical", "horizontal" | "horizontal" (renderer) | Thumbnail Position. See the usage notes for this block. |
arrows | "visible", "hover", "none" | "hover" (renderer) | Arrows Style. See the usage notes for this block. |
maxHeight | number | Not declared here | Max Height (0 - Auto). See the usage notes for this block. |
backgroundColor | string | Not declared here | Background colour. Theme-derived appearance can still depend on the surrounding section. |
spacing | object | Not declared here | An object of spacing settings. Preserve existing responsive values when changing a single setting. |
animationType | "none", "fade-up", "fade-down", "fade-left", "fade-right", "flip-up", "flip-down", "flip-left", "flip-right", "zoom-in", "zoom-left", "zoom-right" | "" (renderer) | Entrance animation setting. Use a supported editor value; preserve it for unrelated edits. |
screenList | string | "" (renderer) | Comma-separated device names to hide on: mobile, tablet, desktop. An empty string hides on none. |
