Overview
Visual Portfolio provides built-in lightbox functionality for displaying images, videos, and other media in popup overlays. The plugin supports multiple lightbox vendors and extensive customization options.
Lightbox settings are configured in the vp_popup_gallery section at classes/class-settings.php:208
Supported Vendors
Visual Portfolio includes two popular lightbox libraries:
Fancybox
Modern, touch-enabled lightbox with smooth animations.
// Located in: classes/class-settings.php
array (
'name' => 'vendor' ,
'label' => esc_html__ ( 'Vendor Script' , 'visual-portfolio' ),
'type' => 'select' ,
'options' => array (
'fancybox' => esc_html__ ( 'Fancybox' , 'visual-portfolio' ),
'photoswipe' => esc_html__ ( 'PhotoSwipe' , 'visual-portfolio' ),
),
'default' => 'fancybox' ,
)
Features:
Modern UI design
Touch and swipe gestures
Video support (YouTube, Vimeo)
Zoom functionality
Responsive design
Integration:
// Located in: classes/3rd/plugins/class-fancybox.php
class Visual_Portfolio_3rd_Fancybox {
public function __construct () {
$fancybox_handler = 'fancybox' ;
if ( ! isset ( $wp_scripts -> registered [ $fancybox_handler ] ) ) {
// Register Fancybox assets
}
}
}
PhotoSwipe
Lightweight, mobile-friendly image gallery.
// Located in: classes/class-assets.php
if ( 'photoswipe' === $popup_vendor && apply_filters ( 'vpf_enqueue_plugin_photoswipe' , true ) ) {
self :: store_used_assets ( 'visual-portfolio-plugin-photoswipe' , true , 'script' );
self :: store_used_assets ( 'visual-portfolio-popup-photoswipe' , true , 'style' );
}
Features:
Minimal UI
No dependencies
Hardware-accelerated animations
History API support
Fullscreen mode
PhotoSwipe is recommended for image-heavy portfolios due to its lightweight nature and excellent mobile performance.
Click Actions
Configure what happens when users click portfolio items:
// Located in: classes/class-admin.php:2730
'items_click_action' => array (
'popup_gallery' => array (
'value' => 'popup_gallery' ,
'title' => esc_html__ ( 'Popup' , 'visual-portfolio' ),
),
'url' => array (
'value' => 'url' ,
'title' => esc_html__ ( 'URL' , 'visual-portfolio' ),
),
'false' => array (
'value' => 'false' ,
'title' => esc_html__ ( 'None' , 'visual-portfolio' ),
),
)
Open images in lightbox overlay with gallery navigation.
Configuration Options:
// Located in: classes/class-admin.php:2805
'items_click_action_popup_title_source' => array (
'none' => esc_html__ ( 'None' , 'visual-portfolio' ),
'title' => esc_html__ ( 'Image Title' , 'visual-portfolio' ),
'caption' => esc_html__ ( 'Image Caption' , 'visual-portfolio' ),
'alt' => esc_html__ ( 'Image Alt' , 'visual-portfolio' ),
'description' => esc_html__ ( 'Image Description' , 'visual-portfolio' ),
'item_title' => esc_html__ ( 'Item Title' , 'visual-portfolio' ),
'item_description' => esc_html__ ( 'Item Description' , 'visual-portfolio' ),
'item_author' => esc_html__ ( 'Item Author' , 'visual-portfolio' ),
)
// Located in: classes/class-admin.php:2832
'items_click_action_popup_description_source' => array (
'none' => esc_html__ ( 'None' , 'visual-portfolio' ),
'title' => esc_html__ ( 'Image Title' , 'visual-portfolio' ),
'caption' => esc_html__ ( 'Image Caption' , 'visual-portfolio' ),
'alt' => esc_html__ ( 'Image Alt' , 'visual-portfolio' ),
'description' => esc_html__ ( 'Image Description' , 'visual-portfolio' ),
'item_title' => esc_html__ ( 'Item Title' , 'visual-portfolio' ),
'item_description' => esc_html__ ( 'Item Description' , 'visual-portfolio' ),
'item_author' => esc_html__ ( 'Item Author' , 'visual-portfolio' ),
)
Direct link to custom URL or post permalink.
Disable click actions entirely.
Global Settings
Configure lightbox behavior globally:
Enable for WordPress Images
// Located in: classes/class-settings.php
array (
'name' => 'enable_on_wordpress_images' ,
'label' => esc_html__ ( 'Lightbox for WordPress Images' , 'visual-portfolio' ),
'desc' => esc_html__ ( 'Enable lightbox for WordPress native galleries and images.' , 'visual-portfolio' ),
'type' => 'toggle' ,
)
When enabled, the lightbox applies to:
WordPress gallery blocks
Individual image blocks
Images in content with data-fancybox or lightbox classes
Asset Management
Lightbox scripts are conditionally loaded:
// Located in: classes/class-assets.php
class Visual_Portfolio_Assets {
/**
* Store which assets are used on the page
*/
public static function store_used_assets ( $name , $value = true , $type = 'script' ) {
if ( ! isset ( self :: $stored_assets [ $type ] ) ) {
self :: $stored_assets [ $type ] = array ();
}
self :: $stored_assets [ $type ][ $name ] = $value ;
}
}
Lightbox assets are only loaded when needed to optimize performance. The plugin detects popup usage and enqueues scripts accordingly.
Third-Party Integrations
Elementor Lightbox Conflict Resolution
// Located in: classes/3rd/plugins/class-elementor.php
class Visual_Portfolio_3rd_Elementor {
public $lightbox_fix_added = false ;
public function __construct () {
add_action ( 'wp_body_open' , array ( $this , 'maybe_fix_elementor_lightbox_conflict' ) );
add_action ( 'wp_footer' , array ( $this , 'maybe_fix_elementor_lightbox_conflict' ), 20 );
}
/**
* Fix Elementor lightbox conflict
*/
public function maybe_fix_elementor_lightbox_conflict () {
if ( $this -> lightbox_fix_added ) {
return ;
}
// Prevent Elementor lightbox from interfering
$items . find ( '.vp-portfolio__item a:not([data-elementor-open-lightbox])' ) . each ( function () {
// Handle conflicts
});
}
}
Enfold Theme Integration
// Located in: classes/3rd/themes/class-enfold.php
class Visual_Portfolio_3rd_Enfold {
public function __construct () {
// Disable Enfold lightbox by adding classname
add_filter ( 'vpf_extend_portfolio_class' , array ( $this , 'disable_lightbox_class' ) );
}
/**
* Disable Enfold lightbox by adding classname
*/
public function disable_lightbox_class ( $class_name ) {
return $class_name . ' noLightbox' ;
}
}
Media Types
Supported media types in lightbox:
Images
Videos
HTML Content
Embedded video support:
YouTube
Vimeo
Self-hosted videos
HTML5 video element
Custom HTML in popup:
Inline content
AJAX-loaded content
iFrame embeds
oEmbed Integration
Automatic video embedding in lightbox:
// Located in: class-visual-portfolio.php:312
public function get_oembed_data ( $url , $width = null , $height = null ) {
$cache_name = 'vp_oembed_data_' . $url . ( $width ? $width : '' ) . ( $height ? $height : '' );
$cached = get_transient ( $cache_name );
if ( $cached ) {
return $cached ;
}
$oembed = _wp_oembed_get_object ();
$provider = $oembed -> get_provider ( $url , $args );
$data = $oembed -> fetch ( $provider , $url , $args );
// Cache for 24 hours
set_transient ( $cache_name , $data , DAY_IN_SECONDS );
return $data ;
}
Premium Features
The following features are available in Visual Portfolio Pro:
// Located in: classes/class-admin.php:2858
array (
'type' => 'pro_note' ,
'label' => esc_html__ ( 'Premium Only' , 'visual-portfolio' ),
'description' => '<ul>
<li>' . esc_html__ ( 'Manage media object priority' , 'visual-portfolio' ) . '</li>
<li>' . esc_html__ ( 'Quick View for posts and pages' , 'visual-portfolio' ) . '</li>
<li>' . esc_html__ ( 'Popup media item deep linking' , 'visual-portfolio' ) . '</li>
<li>' . esc_html__ ( 'Custom image for Popup' , 'visual-portfolio' ) . '</li>
</ul>' ,
)
Pro Features Include:
Media Priority - Control which media displays first in galleries
Quick View - Post content preview in lightbox
Deep Linking - Direct URLs to specific popup items
Custom Popup Images - Use different images for popup vs. thumbnail
Video Galleries - Advanced video playlist features
Customization
Custom CSS
Target lightbox elements:
/* Fancybox customization */
.fancybox-container {
/* Container styles */
}
.fancybox-slide {
/* Slide styles */
}
/* PhotoSwipe customization */
.pswp__bg {
/* Background overlay */
}
.pswp__img {
/* Image styles */
}
JavaScript Hooks
// Fancybox initialization
jQuery ( document ). on ( "click" , "[data-fancybox]" , function ( e ) {
// Custom logic
});
// PhotoSwipe events
photoswipeInstance . listen ( 'afterChange' , function () {
// Custom logic after slide change
});
Filter Hooks
// Enable/disable PhotoSwipe
apply_filters ( 'vpf_enqueue_plugin_photoswipe' , true );
// Modify popup classes
apply_filters ( 'vpf_extend_portfolio_class' , $class_name );
Performance Optimization
Lightbox images support lazy loading:
Images load only when lightbox opens
Reduces initial page load time
Compatible with lazy loading plugins
// Only load when needed
if ( $has_popup ) {
wp_enqueue_script ( 'visual-portfolio-plugin-' . $popup_vendor );
}
oEmbed data cached for 24 hours
Lightbox markup cached
Scripts concatenated and minified
Accessibility
Lightbox implementation follows accessibility best practices:
Keyboard navigation (arrow keys, ESC)
Screen reader support
Focus management
ARIA attributes
Skip links for navigation
Troubleshooting
Common causes:
JavaScript conflicts with other plugins
Theme CSS overriding styles
Cache not cleared after settings change
Solution: Check browser console for errors and try switching vendors.
Check:
Image URLs are valid
CORS settings for external images
PHP memory limit for large images
Verify:
oEmbed URL format is correct
Video is publicly accessible
Provider supports embedding
See Also
Item Styles Configure item click actions
Assets Management Understanding asset loading
Third-Party Integrations Plugin compatibility features
Settings API Global lightbox settings