Skip to content
Square Orb Documentation

The Lightbox Experience

The Lightbox overlay provides an immersive, full-screen viewing experience for photos and videos. It can be customized globally under Square Orb > Presentation Defaults > Lightbox Settings, or overridden at the individual block level.

  • Transitions: Choose from 11 animation styles when opening or navigating between images (Instant Swap, Smooth Fade, Gaussian Blur, Clip Wipe, Stage Curtain, Vertical Swipe, Directional Slide, Pop & Zoom, Elastic Bounce, 3D Axis Flip, or Quarter Spin).
  • Overlay & Media Styling: Customize the overlay backdrop color and opacity, media border color, width, and corner radius.
  • Controls & Slideshow: Enable automated slideshow playback, configure slide intervals (in seconds), toggle pause-on-hover, and style UI navigation buttons (background, color, border radius).
  • Filmstrip Navigation: Display a bottom thumbnail strip allowing viewers to quickly scrub through and jump directly to any asset in the gallery.
  • Metadata & EXIF Display: Display image titles, descriptions, captions, and technical camera EXIF metadata (camera model, aperture, shutter speed, ISO, focal length).
  • Social Sharing: Provide direct sharing triggers for social networks and direct asset URL copying.
  • Video Playback: Seamlessly renders YouTube, Vimeo, and self-hosted HTML5 MP4/WebM video players. Enable Autoplay Lightbox Videos to start playback automatically upon opening.

Lightbox Lifecycle & Media Flow

flowchart TD
    A["Visitor Clicks Gallery Item"] --> B["Open Full-Screen Lightbox Overlay"]
    B --> C["Update Browser URL Hash: #sorb-img-{id}"]
    B --> D{"Asset Media Type"}
    
    D -->|Static Photograph| E["Load High-Res Image: sorb-pro-highres"]
    E --> F["Display Camera EXIF Metadata Badges"]
    
    D -->|Video URL Present| G["Initialize Responsive Video Player"]
    G --> G1["YouTube / Vimeo / HTML5 MP4"]
    G1 --> G2{"Autoplay Videos Enabled?"}
    G2 -->|Yes| G3["Start Video Playback Immediately"]
    G2 -->|No| G4["Display Video Player Paused"]

    F --> H["Mount Interactive Filmstrip & Navigation"]
    G3 --> H
    G4 --> H

    H --> I["Navigation Event<br/>Arrow Keys / Touch Swipe / Filmstrip Click"]
    I --> J["Unload Active Video Player<br/>Prevent Background Audio"]
    J --> K["Trigger Selected CSS Transition<br/>1 of 11 GPU-Accelerated Animations"]
    K --> D

    H --> L["Close Event<br/>Escape Key / Matte Click / Browser Back"]
    L --> M["Teardown Modal & Restore Document Focus"]

Available Transitions

Square Orb includes 11 CSS-accelerated lightbox transition effects:

ValueLabelEffect
noneInstant SwapImmediate switch with zero animation delay
fadeSmooth Opacity FadeCurrent image dissolves to 0 opacity while new image fades in
blurGaussian Blur DissolveRack-focus simulation: blurs and scales slightly out, then sharpens into view
wipeHardware Accelerated Clip WipeGPU-accelerated clip-path reveal sweeping left to right
curtainStage CurtainSymmetrical clip-path reveal sweeping outward from the center in both directions
swipeVertical SwipeDirection-aware vertical clip-path reveal (top-down for next, bottom-up for previous)
slideDirectional SlideSmooth horizontal slide on the X axis (translateX) based on navigation direction
zoomPop & ZoomScales in from 80% to 100% with subtle spring easing
bounceElastic BounceDramatic entrance scaling from 60% with strong spring overshoot (cubic-bezier(0.34, 1.56, 0.64, 1))
flip3D Axis Flip3D perspective rotation on the Y-axis (rotateY) inside a 1200px perspective stage
spinQuarter SpinDirection-aware 90° rotational spin accompanied by a smooth scale transition

Navigation & Accessibility

Square Orb’s lightbox is built with accessibility and mobile responsiveness in mind:

  • Keyboard Navigation:
    • Escape: Closes the lightbox and returns focus to the trigger element.
    • ArrowLeft / ArrowRight: Navigates to the previous or next asset in the sequence.
    • Spacebar: Toggles slideshow play/pause when the slideshow feature is enabled.
    • Tab / Shift + Tab: Cycles through active focusable elements inside the modal using an accessibility focus trap.
  • Touch & Swipe Gestures:
    • On mobile and tablet touchscreens, swipe left to advance to the next slide, or swipe right to return to the previous slide.
  • Deep Linking & Browser History:
    • When enabled, opening an image updates the browser’s URL hash to #sorb-img-{id}.
    • Users can copy and share the direct URL to land directly on a specific photo in the lightbox.
    • Pressing the browser’s Back button closes the lightbox rather than navigating away from the page.
  • Responsive Filmstrip:
    • The bottom thumbnail strip automatically scrolls to keep the currently active image centered and visible.
    • Users can click or tap any thumbnail to jump immediately to that asset.