CSS Variables

Visual Portfolio uses CSS custom properties (CSS variables) to provide a flexible and maintainable styling system. These variables allow you to customize the appearance without writing complex CSS overrides.

Global Variables

Global CSS variables are defined on the :root selector and apply to all portfolio instances. Location: assets/css/_variables-main.scss:4-24

Colors

:root {
    --vp-color-brand: #2540cc;
    --vp-color-gray: #6c7781;
    --vp-color-gray-darken: #4b4b4b;
    --vp-color-gray-light: #e8e8e8;
    --vp-color-gray-lighten: #f7f7f7;
    --vp-color-red: #b71515;
}

Usage Example:

.vp-portfolio__item {
    border-color: var(--vp-color-gray-light);
}

.vp-portfolio__item:hover {
    border-color: var(--vp-color-brand);
}

Border & Radius

:root {
    --vp-border-radius: 5px;
}

Gap & Spacing

:root {
    --vp-items__gap: 0;
}

.vp-portfolio__items {
    --vp-items__gap-vertical: var(--vp-items__gap);
}

The --vp-items__gap variable is dynamically set based on the portfolio’s gap settings.

Transitions

:root {
    --vp-transition-duration: 0.3s;
    --vp-transition-easing: ease-in-out;
    --vp-interactive__transition-duration: 0.2s;
    --vp-interactive__transition-easing: ease-in-out;
}

Portfolio Container Variables

These variables apply to the .vp-portfolio container. Location: assets/css/_variables-main.scss:31-38

.vp-portfolio {
    --vp-wrap__min-height: 114px;
    --vp-elements__gap: 20px;
    --vp-images__object-fit: cover;
    --vp-images__object-position: 50% 50%;
}

Customize per portfolio:

.vp-portfolio.vp-id-123 {
    --vp-elements__gap: 30px;
    --vp-images__object-fit: contain;
}

Spinner Variables

Loader spinner customization. Location: assets/css/_variables-main.scss:40-47

.vp-spinner {
    --vp-spinner__color: currentcolor;
    --vp-spinner__size: 20px;
    --vp-spinner__border-size: 2px;
    --vp-spinner__speed: 0.3s;
    --vp-spinner--background__color: var(--vp-spinner__color);
    --vp-spinner--background__opacity: 0.3;
}

Layout: Slider

Slider layout specific variables. Location: assets/css/_variables-slider.scss:4-38

Arrows

.vp-portfolio {
    --vp-layout-slider--arrows__width: 2em;
    --vp-layout-slider--arrows__height: 2em;
    --vp-layout-slider--arrows__offset: 10px;
    --vp-layout-slider--arrows__compensation: 10px;
    --vp-layout-slider--arrows__color: var(--vp-color-gray);
    --vp-layout-slider--arrows__background-color: #fff;
    --vp-layout-slider--arrows__border-radius: 50%;
    --vp-layout-slider--arrows__box-shadow: 0 0 7px 2px rgba(0, 0, 0, 4%);
    --vp-layout-slider--arrows__opacity: 0.5;
    --vp-layout-slider--arrows-hover__box-shadow: 0 2px 15px 2px rgba(0, 0, 0, 4%);
    --vp-layout-slider--arrows-hover__opacity: 1;
}

Customize arrows:

.vp-portfolio[data-vp-layout="slider"] {
    --vp-layout-slider--arrows__width: 3em;
    --vp-layout-slider--arrows__height: 3em;
    --vp-layout-slider--arrows__background-color: var(--vp-color-brand);
    --vp-layout-slider--arrows__color: #fff;
    --vp-layout-slider--arrows__border-radius: 8px;
}

Bullets

.vp-portfolio {
    --vp-layout-slider--bullets__margin-top: 2em;
    --vp-layout-slider--bullets__width: 0.4em;
    --vp-layout-slider--bullets__height: 0.4em;
    --vp-layout-slider--bullets__gap: 0.4em;
    --vp-layout-slider--bullets__compensation: 4px;
    --vp-layout-slider--bullets__background-color: currentcolor;
    --vp-layout-slider--bullets__border-radius: 50%;
    --vp-layout-slider--bullets__opacity: 0.2;
    --vp-layout-slider--bullets-hover__opacity: 0.5;
    --vp-layout-slider--bullets-active__opacity: 1;
}

Customize bullets:

.vp-portfolio[data-vp-layout="slider"] {
    --vp-layout-slider--bullets__width: 0.8em;
    --vp-layout-slider--bullets__height: 0.8em;
    --vp-layout-slider--bullets__background-color: var(--vp-color-brand);
    --vp-layout-slider--bullets__border-radius: 4px;
}

Thumbnails

.vp-portfolio {
    --vp-layout-slider--thumbnails__opacity: 0.5;
    --vp-layout-slider--thumbnails-hover__opacity: 1;
    --vp-layout-slider--thumbnails-active__opacity: 1;
}

Slider Transitions

.vp-portfolio {
    --vp-layout-slider__transition-duration: var(--vp-interactive__transition-duration);
    --vp-layout-slider__transition-easing: var(--vp-interactive__transition-easing);
}

Items Style: Fade

Fade item style variables. Location: templates/items-list/items-style/fade/_variables.scss:4-63

.vp-portfolio__items-style-fade {
    /* Links */
    --vp-items-style-fade--links__text-decoration: none;
    
    /* Image */
    --vp-items-style-fade--image__border-radius: 0;
    --vp-items-style-fade--image__transform: none;
    --vp-items-style-fade--image-hover__transform: scale(1.05);
    
    /* Overlay */
    --vp-items-style-fade--overlay__text-decoration: none;
    --vp-items-style-fade--overlay__color: #fff;
    --vp-items-style-fade--overlay__background: #000;
    --vp-items-style-fade--overlay__border-radius: 0;
    --vp-items-style-fade--overlay__padding: 2em;
    --vp-items-style-fade--overlay__margin: 0;
    --vp-items-style-fade--overlay-items__gap: 1.5em;
    
    /* Meta Icon */
    --vp-items-style-fade--meta-icon__font-size: 2em;
    
    /* Meta Categories */
    --vp-items-style-fade--meta-categories__font-size: 0.9em;
    --vp-items-style-fade--meta-categories__font-weight: 500;
    --vp-items-style-fade--meta-categories__text-transform: uppercase;
    --vp-items-style-fade--meta-categories__text-decoration: none;
    --vp-items-style-fade--meta-categories__opacity: 0.8;
    --vp-items-style-fade--meta-categories__gap: 0 0.4em;
    --vp-items-style-fade--meta-categories__separator: ", ";
    
    /* Meta Inline */
    --vp-items-style-fade--meta-inline__font-weight: 400;
    --vp-items-style-fade--meta-inline__line-height: 2;
    --vp-items-style-fade--meta-inline__font-opacity: 0.8;
    --vp-items-style-fade--meta-inline__gap: 0 1em;
    
    /* Meta Parts */
    --vp-items-style-fade--meta-part-icon__offset: 0.5em;
    
    /* Meta Title */
    --vp-items-style-fade--meta-title__font-size: 1.3em;
    
    /* Meta Excerpt */
    --vp-items-style-fade--meta-excerpt__line-height: 1.5;
    --vp-items-style-fade--meta-excerpt__opacity: 0.8;
    
    /* Meta Staggering Animation */
    --vp-items-style-fade--meta-staggering__index: 1;
    --vp-items-style-fade--meta-staggering__transition-duration: 0.25s;
    --vp-items-style-fade--meta-staggering__transition-delay: 0.07s;
    --vp-items-style-fade--meta-staggering__transition-easing: cubic-bezier(0.25, 0.46, 0.45, 0.94);
    
    /* Transitions */
    --vp-items-style-fade-transition-duration: var(--vp-interactive__transition-duration);
    --vp-items-style-fade-transition-easing: var(--vp-interactive__transition-easing);
    --vp-items-style-fade--image__transition-duration: var(--vp-items-style-fade-transition-duration);
    --vp-items-style-fade--image__transition-easing: var(--vp-items-style-fade-transition-easing);
    --vp-items-style-fade--overlay__transition-duration: var(--vp-items-style-fade-transition-duration);
    --vp-items-style-fade--overlay__transition-easing: var(--vp-items-style-fade-transition-easing);
}

Customize fade style:

.vp-portfolio__items-style-fade {
    --vp-items-style-fade--overlay__color: #f0f0f0;
    --vp-items-style-fade--overlay__background: linear-gradient(to bottom, transparent, rgba(0,0,0,0.9));
    --vp-items-style-fade--overlay__padding: 3em;
    --vp-items-style-fade--image-hover__transform: scale(1.1) rotate(2deg);
}

Items Style: Fly

Fly item style variables. Location: templates/items-list/items-style/fly/_variables.scss:4-59

.vp-portfolio__items-style-fly {
    /* Links */
    --vp-items-style-fly--links__text-decoration: none;
    
    /* Image */
    --vp-items-style-fly--image__border-radius: 0;
    --vp-items-style-fly--image__transform: none;
    --vp-items-style-fly--image-hover__transform: none;
    
    /* Overlay */
    --vp-items-style-fly--overlay__text-decoration: none;
    --vp-items-style-fly--overlay__color: #fff;
    --vp-items-style-fly--overlay__background: #000;
    --vp-items-style-fly--overlay__border-radius: 0;
    --vp-items-style-fly--overlay__padding: 2em;
    --vp-items-style-fly--overlay__margin: 0;
    --vp-items-style-fly--overlay-items__gap: 1.5em;
    
    /* Meta Icon */
    --vp-items-style-fly--meta-icon__font-size: 2em;
    
    /* Meta Categories */
    --vp-items-style-fly--meta-categories__font-size: 0.9em;
    --vp-items-style-fly--meta-categories__font-weight: 500;
    --vp-items-style-fly--meta-categories__text-transform: uppercase;
    --vp-items-style-fly--meta-categories__text-decoration: none;
    --vp-items-style-fly--meta-categories__opacity: 0.8;
    --vp-items-style-fly--meta-categories__gap: 0 0.4em;
    --vp-items-style-fly--meta-categories__separator: ", ";
    
    /* Meta Inline */
    --vp-items-style-fly--meta-inline__font-weight: 400;
    --vp-items-style-fly--meta-inline__line-height: 2;
    --vp-items-style-fly--meta-inline__font-opacity: 0.8;
    --vp-items-style-fly--meta-inline__gap: 0 1em;
    
    /* Meta Parts */
    --vp-items-style-fly--meta-part-icon__offset: 0.5em;
    
    /* Meta Title */
    --vp-items-style-fly--meta-title__font-size: 1.3em;
    
    /* Meta Excerpt */
    --vp-items-style-fly--meta-excerpt__line-height: 1.5;
    --vp-items-style-fly--meta-excerpt__opacity: 0.8;
    
    /* Transitions */
    --vp-items-style-fly-transition-duration: var(--vp-interactive__transition-duration);
    --vp-items-style-fly-transition-easing: var(--vp-interactive__transition-easing);
    --vp-items-style-fly--image__transition-duration: var(--vp-items-style-fly-transition-duration);
    --vp-items-style-fly--image__transition-easing: var(--vp-items-style-fly-transition-easing);
    --vp-items-style-fly--overlay__transition-duration: var(--vp-items-style-fly-transition-duration);
    --vp-items-style-fly--overlay__transition-easing: var(--vp-items-style-fly-transition-easing);
    --vp-items-style-fly--caption__transition-duration: var(--vp-items-style-fly-transition-duration);
    --vp-items-style-fly--caption__transition-easing: var(--vp-items-style-fly-transition-easing);
}

Popup gallery CSS variables for PhotoSwipe and Fancybox. Location: assets/css/_variables-popup.scss:4-17

.vp-pswp,
.vp-fancybox {
    --vp-popup__z-index: 1500;
    
    /* Thumbnails */
    --vp-popup--thumbnails__size: 160px;
    --vp-popup--thumbnails__aspect-ratio: 10 / 7;
    --vp-popup--thumbnails__background-color: #1e1e1e;
    --vp-popup--thumbnails--items__border-color: var(--vp-color-brand);
    --vp-popup--thumbnails--scrollbar__size: 7px;
    --vp-popup--thumbnails--scrollbar-track__background-color: #1f1f1f;
    --vp-popup--thumbnails--scrollbar-thumb__background-color: #424242;
    --vp-popup--thumbnails--scrollbar-thumb__border-radius: 10px;
}

Customize popup:

.vp-pswp {
    --vp-popup__z-index: 9999;
    --vp-popup--thumbnails__size: 200px;
    --vp-popup--thumbnails--items__border-color: #fff;
}

Practical Examples

Dark Theme Portfolio

.vp-portfolio.dark-theme {
    --vp-color-brand: #4a90e2;
    --vp-color-gray: #b0b0b0;
    --vp-color-gray-darken: #e0e0e0;
    --vp-color-gray-light: #333;
    --vp-color-gray-lighten: #1a1a1a;
    
    background-color: #1a1a1a;
    color: #e0e0e0;
}

.vp-portfolio.dark-theme .vp-portfolio__items-style-fade {
    --vp-items-style-fade--overlay__color: #e0e0e0;
    --vp-items-style-fade--overlay__background: rgba(26, 26, 26, 0.95);
}

Rounded Corners Design

.vp-portfolio.rounded-design {
    --vp-border-radius: 15px;
}

.vp-portfolio.rounded-design .vp-portfolio__items-style-fade {
    --vp-items-style-fade--image__border-radius: var(--vp-border-radius);
    --vp-items-style-fade--overlay__border-radius: var(--vp-border-radius);
}

.vp-portfolio.rounded-design[data-vp-layout="slider"] {
    --vp-layout-slider--arrows__border-radius: var(--vp-border-radius);
}

Smooth Animations

.vp-portfolio.smooth-animations {
    --vp-transition-duration: 0.6s;
    --vp-transition-easing: cubic-bezier(0.4, 0, 0.2, 1);
    --vp-interactive__transition-duration: 0.4s;
    --vp-interactive__transition-easing: cubic-bezier(0.4, 0, 0.2, 1);
}

Large Gaps

.vp-portfolio.large-gaps {
    --vp-elements__gap: 40px;
}

.vp-portfolio.large-gaps .vp-portfolio__items {
    --vp-items__gap-vertical: 40px;
}

Custom Overlay Style

.vp-portfolio__items-style-fade.custom-overlay {
    --vp-items-style-fade--overlay__background: 
        linear-gradient(
            180deg,
            rgba(0, 0, 0, 0) 0%,
            rgba(0, 0, 0, 0.7) 50%,
            rgba(0, 0, 0, 0.95) 100%
        );
    --vp-items-style-fade--overlay__padding: 2em 1.5em;
    --vp-items-style-fade--meta-title__font-size: 1.8em;
}

Target Specific Portfolio

/* Target by ID */
.vp-portfolio.vp-id-123 {
    --vp-color-brand: #e74c3c;
}

/* Target by custom class */
.vp-portfolio.featured-portfolio {
    --vp-items-style-fade--overlay__background: rgba(231, 76, 60, 0.9);
}

Using in Custom CSS

Add custom CSS through WordPress Customizer or plugin settings: Settings > Visual Portfolio > Custom CSS

/* Override global brand color */
:root {
    --vp-color-brand: #ff6b6b;
}

/* Customize specific portfolio */
.vp-portfolio.vp-id-456 {
    --vp-elements__gap: 25px;
}

.vp-portfolio.vp-id-456 .vp-portfolio__items-style-fade {
    --vp-items-style-fade--overlay__padding: 3em;
}

Dynamic Variables via PHP

Set CSS variables dynamically through filters:

add_action( 'vpf_after_wrapper_start', function( $options, $style_options ) {
    $brand_color = get_option( 'my_brand_color', '#2540cc' );
    ?>
    <style>
        .vp-portfolio.vp-id-<?php echo esc_attr( $options['id'] ); ?> {
            --vp-color-brand: <?php echo esc_attr( $brand_color ); ?>;
        }
    </style>
    <?php
}, 10, 2 );

Browser Support

CSS Custom Properties are supported in:

Chrome 49+
Firefox 31+
Safari 9.1+
Edge 15+
iOS Safari 9.3+
Android 5+

For older browsers, fallback values are defined in the SCSS source files.

Best Practices

Use inheritance - Define common values at root level, override as needed
Stay organized - Group related variables together
Use calc() - Perform calculations with variables: calc(var(--base-size) * 2)
Fallback values - Provide fallbacks for older browsers: background: var(--bg-color, #fff);
Meaningful names - Use descriptive variable names that indicate purpose
Test thoroughly - Check custom values across different layouts and styles
Document changes - Comment complex variable combinations

Development

Customization

API Reference

Contributing

Global Variables

Colors

Border & Radius

Gap & Spacing

Transitions

Portfolio Container Variables

Spinner Variables

Layout: Slider

Arrows

Bullets

Thumbnails

Slider Transitions

Items Style: Fade

Items Style: Fly

Practical Examples

Dark Theme Portfolio

Rounded Corners Design

Smooth Animations

Large Gaps

Custom Overlay Style

Target Specific Portfolio

Using in Custom CSS

Dynamic Variables via PHP

Browser Support

Best Practices

Build docs developers (and LLMs) love

Development

Customization

API Reference

Contributing

​Global Variables

​Colors

​Border & Radius

​Gap & Spacing

​Transitions

​Portfolio Container Variables

​Spinner Variables

​Layout: Slider

​Arrows

​Bullets

​Thumbnails

​Slider Transitions

​Items Style: Fade

​Items Style: Fly

​Popup Gallery Variables

​Practical Examples

​Dark Theme Portfolio

​Rounded Corners Design

​Smooth Animations

​Large Gaps

​Custom Overlay Style

​Target Specific Portfolio

​Using in Custom CSS

​Dynamic Variables via PHP

​Browser Support

​Best Practices

​Related Resources

Build docs developers (and LLMs) love

Global Variables

Colors

Border & Radius

Gap & Spacing

Transitions

Portfolio Container Variables

Spinner Variables

Layout: Slider

Arrows

Bullets

Thumbnails

Slider Transitions

Items Style: Fade

Items Style: Fly

Popup Gallery Variables

Practical Examples

Dark Theme Portfolio

Rounded Corners Design

Smooth Animations

Large Gaps

Custom Overlay Style

Target Specific Portfolio

Using in Custom CSS

Dynamic Variables via PHP

Browser Support

Best Practices

Related Resources