> For the complete documentation index, see [llms.txt](https://docs.realmacsoftware.com/elements-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmacsoftware.com/elements-docs/using-elements/components/content-and-media/gallery.md).

# Gallery

The Gallery component turns a Resources folder into a responsive media grid with optional captions, author information, and a full-screen lightbox. It can combine images, YouTube and Vimeo links, and MP4 video, or build the grid from a Remote Folder of images already on your web server.

{% embed url="<https://youtu.be/LwmA-IZNQIs>" %}

{% hint style="success" %}
Add a YouTube or Vimeo video by dragging its URL from your browser into Resources. Playlist URLs can also be added.
{% endhint %}

### Supported Content and File Types

* JPG
* PNG
* YouTube
* Vimeo
* MP4

The Gallery expects a folder rather than a single image.

Remote Folder galleries support JPG, PNG, GIF, WebP, and AVIF images. Video and author information require the Resources source.

### How to Use Gallery

You’ll find Gallery under **Media** in the Components list.

1. Create a folder in Resources and add the images or videos.
2. Drag **Gallery** onto the page.
3. Drop the Resources folder into **Media → Resources**.
4. Set the column count, gap, and thumbnail ratio.
5. Configure thumbnail metadata and lightbox styling.
6. Preview images and videos in a browser.

{% hint style="info" %}
For sharp modern displays, use gallery images at least 1200 pixels wide. [Squash for macOS](https://www.realmacsoftware.com/squash/) can batch resize and compress them.
{% endhint %}

### Using a Remote Folder

Switch **Media → Source** to **Remote Folder** to build the gallery from a folder of images that already lives on your web server — useful when photos are uploaded by FTP, a CMS, or another app. Enter the folder as a full URL or a path relative to your published site, for example `https://example.com/photos/holiday` or `/photos/holiday`. The folder must be on the same server as the published site.

The folder is read each time the page loads, so images added or removed later appear in the gallery automatically without republishing:

* Images display in filename order, so number files (`01-sunset.jpg`, `02-harbour.jpg`) to control the sequence.
* Captions are generated from filenames, with hyphens and underscores shown as spaces.
* Upload a smaller companion file ending in `-thumb` (for example `sunset.jpg` and `sunset-thumb.jpg`) to use it as the grid thumbnail for that image.

Remote images are served exactly as uploaded, so resize and compress them before adding them to the folder. In the editor, a Remote Folder gallery shows placeholder thumbnails; preview the page in a browser to see the real images.

{% hint style="warning" %}
Pages containing the Gallery component are published as PHP, so the site must be hosted on a server with PHP support.
{% endhint %}

### Component Settings

#### Media

**Source** chooses between building the gallery from **Resources** or a **Remote Folder** on your web server. Resources is the default.

**Resources** selects the folder containing gallery media.

**Folder** appears for the Remote Folder source and accepts a full URL or a relative path. The folder must be on the same server as your published site.

<figure><img src="/files/8X1bKS0jeDjv4g2LuQtM" alt="The Gallery Media settings with a Resources folder selected"><figcaption><p>The Gallery is built from a folder in Resources.</p></figcaption></figure>

#### Layout

**Columns** sets between 1 and 12 columns and defaults to 3.

**Gap** sets spacing between thumbnails and defaults to theme spacing 3.

<figure><img src="/files/HifWpX00WDFa0UNut2DG" alt="Gallery Layout settings showing Columns and Gap controls"><figcaption><p>Layout controls the number and spacing of gallery columns.</p></figcaption></figure>

#### Thumbnails

**Media**

* **Aspect** — Square, Wide, or Tall. Square is the default and applies to every thumbnail.
* **Radius** — Sets thumbnail corner rounding.
* **Shadow** — Applies a theme shadow.

**Meta Data**

* **Alignment** — Left, Centre, or Right. Left is the default.
* **Margin** — Space above metadata; defaults to 0.
* **Spacing** — Space between metadata items; defaults to 0.

**Caption** and **Author** are hidden by default. Enabling either reveals Color, Font, and Size. Both default to Text 50, the Heading font, and Small size.

{% hint style="warning" %}
One Aspect applies to the complete gallery. Use a custom Grid layout when mixed thumbnail ratios must remain visible.
{% endhint %}

<figure><img src="/files/EZjoDZaKaOnBr3mskFpp" alt="Gallery Thumbnails settings for aspect, metadata, caption, and author styling"><figcaption><p>Thumbnail media and metadata can be styled independently.</p></figcaption></figure>

#### Lightbox

**Preview** opens the lightbox in Edit mode and is off by default.

**Media** has separate Radius and Shadow controls for the enlarged media.

**Meta Data** controls Alignment, Margin, and Spacing below the lightbox media. Alignment defaults to Centre, Margin to theme spacing 3, and Spacing to 0.

Caption and Author are hidden by default and each provides Color, Font, and Size when enabled.

<figure><img src="/files/m2WJ8Q90EnoqCcjYx7kg" alt="Gallery Lightbox settings for media and metadata"><figcaption><p>The lightbox can use different media and metadata styling from the grid.</p></figcaption></figure>

#### Overlay

**Color** sets the page backdrop and defaults to Surface 50.

**Opacity** defaults to 20%.

**Blur** defaults to 3 pixels.

<figure><img src="/files/5ak3t1T06atkkwxLEOSi" alt="Gallery Overlay controls for colour, opacity, and blur"><figcaption><p>Overlay settings draw attention to the selected media.</p></figcaption></figure>

#### Navigation

General controls set **Border Radius**, **Padding**, and icon **Size** for navigation buttons. Defaults are Full radius, theme spacing 2, and 24 pixels.

Use **State** to switch between Default and Hover styling.

**Close Button** and **Next & Previous Buttons** each provide Background, Icon, and Opacity for both states. Default opacity is 100%.

<figure><img src="/files/voJrjJwMnCK7wTJHb42j" alt="Gallery Navigation controls for close, next, and previous buttons"><figcaption><p>Navigation buttons have independent Default and Hover styles.</p></figcaption></figure>

### Accessibility

Add meaningful captions or image metadata when media conveys information. Keep lightbox controls high contrast, and make sure videos remain usable with keyboard controls.

### Tips and Best Practices

* **Optimise before importing:** Smaller files improve loading and lightbox performance.
* **Use consistent crops:** A shared thumbnail ratio makes the grid feel intentional.
* **Keep controls visible:** Test navigation colours over both light and dark media.

### Related Components

* [Image](/elements-docs/using-elements/components/content-and-media/image.md) — Displays one image with optional lightbox.
* [Image Slider](/elements-docs/using-elements/components/content-and-media/image-slider.md) — Presents images in a swipeable carousel.
* [Grid](/elements-docs/using-elements/components/layout-components/grid.md) — Builds a fully custom media layout.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.realmacsoftware.com/elements-docs/using-elements/components/content-and-media/gallery.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.