PhotoGallery

Interactive photo gallery with lightbox viewer. Displays images in a grid or masonry layout with hover effects and click‑to‑zoom functionality. It is a universal component suitable for any site type.

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: true. Recommendations: count – 3‑12 images for optimal gallery experience; quality – use high‑resolution images (800px+ width) for professional appearance; consistency – use images with similar style/quality for cohesive gallery; diversity – show different angles, contexts, or variations to tell a complete story.

binding

Query binding for loading images dynamically from a data query. CRITICAL: When binding is set, you SHOULD also set urlField explicitly if the image column is not named ‘imageUrl’, ‘url’, ‘image’, ‘src’, or ‘photo’ (auto‑detect list). Common column name ‘image_url’ (with underscore) is NOT auto‑detected — set urlField: ‘image_url’ explicitly. Type: object. Required: false.

binding.query

Query name to bind to. Type: string. Required: false.

binding.field

Field name (optional). Type: string. Required: false.

binding.isReadOnly

Type: boolean. Default: true. Required: false.

urlField

Column name in query results containing image URLs. Auto‑detects: ‘url’, ‘imageUrl’, ‘image’, ‘src’, ‘photo’. Type: string. Required: false. Default: imageUrl.

altField

Column name in query results for alt text. Auto‑detects: ‘alt’, ‘altText’, ‘title’, ‘name’. Type: string. Required: false.

captionField

Column name in query results for captions. Auto‑detects: ‘caption’, ‘description’, ‘text’. Type: string. Required: false.

layout

Gallery layout style. Grid for strict uniform rows, masonry for Pinterest‑style cascading layout. Type: string. Required: false. Options: grid, masonry. Default: grid. Visual Impact: masonry – Images cascade naturally based on height. Professional, modern look. Best for most galleries (photography, mixed content, portfolios, restaurants, showcases). grid – Images arranged in equal‑height rows with cropping. Only use when all images MUST be the exact same size (product thumbnails, team headshots). Recommendations: masonry – DEFAULT CHOICE for all galleries. Shows full images without cropping. Works with any mix of aspect ratios. Use for websites, portfolios, restaurants, events, blogs. grid – Only use when you specifically need uniform thumbnail‑style presentation (product catalog grids, team headshot grids).

columns

Number of columns in the gallery. Automatically responsive (fewer columns on mobile). Type: number. Required: false. Options: 2, 3, 4. Default: 3. Visual Impact: 2 – Large images, emphasis on detail. Good for high‑quality photography or featured work. 3 – Balanced layout, industry standard. Works well for most use cases. 4 – More compact, shows more images at once. Good for product catalogs or large collections. Recommendations: portfolios – Use 3 columns for balanced showcase; products – Use 4 columns for browsing many items; featured‑work – Use 2 columns for impactful presentation.

gap

Spacing between images in pixels. Affects visual density and breathing room. Type: number. Required: false. Default: 16. Visual Impact: 8‑12 – Tight spacing, more images visible, modern compact look. 16‑20 – Balanced spacing, comfortable viewing (recommended default). 24‑32 – Generous spacing, premium feel, emphasizes individual images. Recommendations: default – Use 16px for general galleries; compact – Use 8‑12px for product catalogs with many items; premium – Use 24‑32px for high‑end portfolios or featured work.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Applies to outermost Section container. Type: string. Required: false. Security Note: Parsed by 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‑24px) for visual breathing room
• Optimize images to reasonable sizes (800‑1200px 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 (<8px) or too large (>40px)

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

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