PhotoGallery

An interactive photo gallery that includes a lightbox viewer, offering grid or masonry layouts with hover effects and click‑to‑zoom functionality. It can be used on any type of site.

Use Cases

• Product catalogs (e‑commerce, retail, marketplaces)
• Portfolio showcases (photographers, designers, artists)
• Team photos (company pages, about pages, staff directories)
• Before/after comparisons (transformations, renovations, progress)
• Property listings (real estate, rentals, vacation homes)
• Project showcases (case studies, work samples, completed projects)
• Image documentation (processes, tutorials, step‑by‑step guides)
• Event galleries (weddings, conferences, celebrations)
• Recipe photos (food blogs, cooking sites, restaurant menus)
• Travel photography (destination guides, travel blogs)

Properties

images

Array of image objects to display in the gallery. Each image should have url, and optionally alt text and caption. Type: array. Required.

Tip: Provide 3‑12 high‑resolution images (800 px + width) that share a consistent style. Show varied angles or contexts to tell a complete story.

layout

Gallery layout style. Masonry (DEFAULT – preferred) for Pinterest‑style cascading layout, grid for strict uniform rows. Type: string. Options: grid, masonry. Default: masonry.

Visual Impact: masonry – images cascade naturally based on height, giving a professional, modern look; grid – images are arranged in equal‑height rows with cropping, suitable only when all images must be the exact same size.

Tip: Use masonry as the default for most galleries. Choose grid only when you need a uniform thumbnail presentation (e.g., product thumbnails, team headshots).

columns

Number of columns in the gallery. Automatically responsive (fewer columns on mobile). Type: number. Options: 2, 3, 4. Default: 3.

Visual Impact: 2 – large images, emphasis on detail; 3 – balanced layout, industry standard; 4 – more compact, shows more images at once.

Tip: Use 3 columns for balanced portfolios, 4 columns for product catalogs, and 2 columns for impactful featured work.

gap

Spacing between images in pixels. Affects visual density and breathing room. Type: number. Default: 16.

Visual Impact: 8‑12 px – tight spacing, modern compact look; 16‑20 px – balanced spacing (recommended default); 24‑32 px – generous spacing, premium feel.

Tip: Use 16 px for general galleries, 8‑12 px for compact product catalogs, or 24‑32 px for high‑end portfolios.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Applies to the outermost Section container. Type: string.

Security Note: Parsed by the cssParser utility. Tenants only affect their own pages (multi‑tenant isolation enforced).

Best Practices

• ALWAYS use PhotoGallery (not Grid + Image) for any image gallery or photo showcase
• Use masonry layout by DEFAULT – it looks professional and handles mixed aspect ratios gracefully
• Only use grid layout when all images must be identical size (product thumbnails, team headshots)
• Use search_unsplash to get high‑quality, contextually relevant images
• Always include alt text for accessibility and SEO
• Use descriptive captions to provide context
• Set appropriate gap (16‑24 px) for visual breathing room
• Optimize images to reasonable sizes (800‑1200 px width for web)
• Group related images together (product variants, project phases, etc.)

Common Mistakes

Using Grid + Image components instead of PhotoGallery for image galleries

Why it's a problem: Grid + Image is a primitive approach that loses lightbox zoom, hover effects, captions, masonry layout, and responsive behavior. The result looks amateur and static compared to PhotoGallery.

Fix: ALWAYS use PhotoGallery component for ANY collection of images. Never use Grid containing Image components as a gallery substitute.

Using fake or made‑up Unsplash URLs instead of calling search_unsplash

Why it's a problem: Fake URLs will 404. Unsplash URLs require specific query parameters and must be from actual API responses.

Fix: ALWAYS call search_unsplash for EACH image. Use the EXACT url returned by the API. Do not shorten or modify URLs.

Missing alt text for images

Why it's a problem: Breaks accessibility for screen reader users and hurts SEO.

Fix: Provide descriptive alt text for every image: what is shown, not just “image 1”.

Using too many columns (4 + ) with large images

Why it's a problem: Images become too small to appreciate detail, especially on smaller screens.

Fix: Stick to 2‑4 columns maximum. Let responsive design reduce columns on mobile.

Mixing portrait and landscape images in grid layout

Why it's a problem: Grid layout forces equal row heights, causing awkward cropping or whitespace.

Fix: Use masonry layout when images have varied aspect ratios.

Not using search_unsplash before generating gallery

Why it's a problem: Without real image URLs, gallery will show broken images or placeholders.

Fix: Call search_unsplash with relevant queries BEFORE creating gallery. One search per distinct image type.

Setting gap too small (< 8 px) or too large (> 40 px)

Why it's a problem: Too small feels cramped and unprofessional. Too large wastes space and breaks visual cohesion.

Fix: Use 16 px as default. Adjust to 12 px (compact) or 24 px (premium) if intentional design choice.