Ctrlk
Buy LicenseDownload Trial
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Gallery

Build a responsive image and video gallery with a lightbox

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.

Add a YouTube or Vimeo video by dragging its URL from your browser into Resources. Playlist URLs can also be added.

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.

For sharp modern displays, use gallery images at least 1200 pixels wide. Squash for macOS can batch resize and compress them.

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.

Pages containing the Gallery component are published as PHP, so the site must be hosted on a server with PHP support.

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.

The Gallery Media settings with a Resources folder selected
The Gallery is built from a folder in Resources.

Layout

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

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

Gallery Layout settings showing Columns and Gap controls
Layout controls the number and spacing of gallery columns.

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.

One Aspect applies to the complete gallery. Use a custom Grid layout when mixed thumbnail ratios must remain visible.

Gallery Thumbnails settings for aspect, metadata, caption, and author styling
Thumbnail media and metadata can be styled independently.

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.

Gallery Lightbox settings for media and metadata
The lightbox can use different media and metadata styling from the grid.

Overlay

Color sets the page backdrop and defaults to Surface 50.

Opacity defaults to 20%.

Blur defaults to 3 pixels.

Gallery Overlay controls for colour, opacity, and blur
Overlay settings draw attention to the selected media.

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%.

Gallery Navigation controls for close, next, and previous buttons
Navigation buttons have independent Default and Hover styles.

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 — Displays one image with optional lightbox.

  • Image Slider — Presents images in a swipeable carousel.

  • Grid — Builds a fully custom media layout.

PreviousAudioNextImage

Last updated

Was this helpful?