Using the Aperture theme lightbox gallery
How to insert a gallery block, configure lightbox options, add captions, and optimise images for the full-screen lightbox in the Aperture theme.
The Aperture theme's lightbox is the central feature of every portfolio post. It opens when a visitor clicks any image in a gallery block, fills the entire viewport, and supports keyboard, touch, and mouse navigation. This article covers inserting galleries, adding captions, and getting the most out of the lightbox UX.
Inserting a gallery block
In the post editor, type / on a new line to open the slash menu and choose Gallery. An upload zone appears — drag and drop image files directly from your desktop or click to browse. Images upload to Cloudflare R2 and are processed for WebP delivery automatically. You can upload multiple files at once; they appear in the order uploaded and can be reordered by drag-and-drop within the gallery block.
Adding captions
Click any image in the gallery block in the editor to reveal a caption text input below it. Captions render in two places: beneath the thumbnail in the grid view, and as an overlay at the bottom of the full-screen lightbox. Keep captions concise — under 100 characters — so they do not obscure the image on mobile screens.
Lightbox navigation
- Keyboard: ← and → arrow keys advance through images; Escape closes the lightbox
- Mouse: click left/right edge of the lightbox viewport to navigate; click outside the image area to close
- Touch (mobile): swipe left or right to advance; swipe down to close
- URL: each lightbox image generates a hash URL (#image-3) — shareable links open directly to that image
Image sizing for the lightbox
The lightbox renders images at up to 90vw × 90vh, which on a 2560px-wide desktop monitor is approximately 2300px wide. Upload images at 2400px wide minimum so the lightbox never shows upscaled, blurry images on high-DPI screens. For portrait-oriented images (wedding, portrait photography), 2400px tall is the equivalent recommendation.
VeloCMS generates responsive srcset attributes for every uploaded image at 400, 800, 1200, 1600, and original widths. The browser selects the correct size automatically — you only need to upload the full-resolution original.
Performance notes
Gallery images below the fold are lazy-loaded — only the first 4 images in a gallery are loaded eagerly on page load. The lightbox preloads the next and previous images in the sequence while the current image is displayed, so navigating feels instant. Total page weight for a 20-image gallery post is typically under 800KB on first load due to WebP compression and lazy loading.