Developer Guide - Better Variations for WooCommerce

Want to extend or customize Better Product Variations? This guide provides the technical details you need to integrate with your custom code, themes, or plugins.

Architecture Overview

Better Product Variations uses a post-query approach that maintains maximum compatibility:

Query Detection: Identifies WooCommerce product queries without modification
Smart Filtering: Uses optimized WP_Query to fetch relevant variations
Result Injection: Inserts variations into query results after the parent product
Zero Template Override: Works through hooks and filters only

This approach ensures compatibility with other plugins and themes while maintaining performance.

Available Filters

bpv_enable_variation_expansion

Purpose: Control whether variation expansion is enabled globally or for specific contexts.

This filter allows you to completely enable or disable the variation expansion feature based on any condition you can imagine. When this filter returns false, no variations will be displayed as separate products anywhere on your site. This is useful for performance optimization, A/B testing, or creating different experiences for different user segments.

What to customize:

Replace the wp_is_mobile() check with your own device detection logic
Change 'accessories' to any category slug where you want to disable variations
Add additional conditions based on user roles, page types, or custom logic

// Disable expansion in specific conditions
add_filter( 'bpv_enable_variation_expansion', function( $enabled ) {
    // Disable on mobile devices
    if ( wp_is_mobile() ) {
        return false;
    }

    // Disable for specific categories
    if ( is_product_category( 'accessories' ) ) {
        return false;
    }

    // Disable on search results pages
    if ( is_search() ) {
        return false;
    }

    // Disable for specific user roles
    if ( ! current_user_can( 'customer' ) ) {
        return false;
    }

    return $enabled;
});Code language: PHP (php)

bpv_get_global_expanded_attributes

Purpose: Modify which attributes are expanded globally across your entire store.

This filter controls the default attributes that will be expanded into separate product listings. For example, if you have variations for Color, Size, and Material, but only want Color variations to appear as separate products by default, you would use this filter. The global settings can still be overridden on a per-product basis.

What to customize:

Replace 'pa_color' with your actual attribute slug (found in Products > Attributes)
Replace 'pa_size' with any attribute slug you want to exclude
Add or remove attributes based on your store’s needs

// Programmatically add attributes
add_filter( 'bpv_get_global_expanded_attributes', function( $attributes ) {
    // Always include color if it exists
    // Note: 'pa_color' is the taxonomy name - replace with your actual attribute slug
    if ( ! in_array( 'pa_color', $attributes ) ) {
        $attributes[] = 'pa_color';
    }

    // Always include material attribute
    if ( ! in_array( 'pa_material', $attributes ) ) {
        $attributes[] = 'pa_material';
    }

    // Remove size from expansion - customers must visit product page to select size
    $attributes = array_diff( $attributes, ['pa_size'] );

    // You can also completely override the array
    // $attributes = ['pa_color', 'pa_brand', 'pa_style'];

    return $attributes;
});Code language: PHP (php)

bpv_get_product_expanded_attributes

Purpose: Control which attributes are expanded for specific products.

This filter gives you granular control over individual products. It runs after the global attribute filter, allowing you to override global settings for specific products. You can disable all variations for certain products, force specific attributes to expand, or implement complex business logic.

What to customize:

Replace 100 with actual product IDs you want to exclude
Replace 't-shirts' with your actual product category slugs
Modify the attribute logic based on your product structure

// Control variations for specific products
add_filter( 'bpv_get_product_expanded_attributes', function( $attributes, $product_id ) {
    // Completely disable variations for specific product IDs
    $disabled_products = [100, 105, 203]; // Replace with your product IDs
    if ( in_array( $product_id, $disabled_products ) ) {
        return false; // Returning false disables all variations
    }

    // Get the product object for more complex logic
    $product = wc_get_product( $product_id );
    if ( ! $product ) {
        return $attributes;
    }

    // Disable variations for products in specific categories
    if ( has_term( 't-shirts', 'product_cat', $product_id ) ) {
        // Only show color variations for t-shirts
        return ['pa_color'];
    }

    // For premium products, show all available attributes
    if ( $product->get_meta( '_is_premium' ) === 'yes' ) {
        // Get all possible attributes for this product
        if ( $product->is_type( 'variable' ) ) {
            return array_keys( $product->get_variation_attributes() );
        }
    }

    // For products under $50, only show the most important attribute
    if ( $product->get_price() < 50 ) {
        // Return only the first attribute
        return array_slice( $attributes, 0, 1 );
    }

    return $attributes;
}, 10, 2 );Code language: PHP (php)

bpv_variation_query_args

Purpose: Modify the WP_Query arguments used to fetch variations.

This filter allows you to control how variations are queried from the database. You can change the sort order, add meta queries, limit the number of variations shown, or add any other WP_Query parameters. This is particularly useful for performance optimization or creating custom ordering logic.

What to customize:

Replace '_custom_priority' with your actual meta key for sorting
Adjust the posts_per_page limit based on your needs
Add your own meta_query conditions

// Sort variations by custom field
add_filter( 'bpv_variation_query_args', function( $args ) {
    // Sort by a custom priority field (lower numbers first)
    $args['meta_key'] = '_custom_priority';
    $args['orderby'] = 'meta_value_num';
    $args['order'] = 'ASC';

    // Limit the number of variations shown per product
    $args['posts_per_page'] = 10;

    // Only show variations that are featured
    $args['meta_query'][] = array(
        'key' => '_featured_variation',
        'value' => 'yes',
        'compare' => '='
    );

    // Sort by multiple criteria
    $args['orderby'] = array(
        'meta_value_num' => 'ASC',  // First by priority
        'menu_order' => 'ASC',      // Then by menu order
        'title' => 'ASC'            // Finally by title
    );

    return $args;
});Code language: PHP (php)

CSS Classes Reference

The plugin adds semantic CSS classes for styling:

/* Main variation item */
.bpv-product-variation {
    /* Your styles */
}

/* Variation attributes container */
.bpv-variation-attributes {
    /* Your styles */
}

/* Attribute presence indicators */
.has-color { }
.has-size { }
.has-material { }

/* Specific attribute values */
.variation-color-red { }
.variation-size-large { }
.variation-material-leather { }

/* Attribute-specific expansion */
.bpv-expanded-variation-color { }
.bpv-expanded-variation-size { }Code language: CSS (css)

Programmatic Control

Enable/disable variations programmatically:

// Temporarily disable for maintenance
add_action( 'init', function() {
     add_filter( 'bpv_enable_variation_expansion', '__return_false' );
});

// Enable only for logged-in users
add_filter( 'bpv_enable_variation_expansion', function( $enabled ) {
    return is_user_logged_in() ? $enabled : false;
});

// Enable only for site admins for easy testing before going live
add_filter( 'bpv_enable_variation_expansion', function( $enabled ) {
    return current_user_can( 'administrator' ) ? $enabled : false;
});Code language: PHP (php)

Custom Query Integration

Make Better Product Variations work with custom product queries:

// Custom product query
$args = array(
    'post_type' => 'product',
    'meta_query' => array(
        array(
            'key' => '_custom_field',
            'value' => 'special',
        )
    )
);

// Add marker for BPV processing
$args['wc_query'] = 'product_query';

$query = new WP_Query( $args );Code language: PHP (php)

Variation Ordering

Control variation display order:

// Sort variations by custom field
add_filter( 'bpv_variation_query_args', function( $args ) {
    $args['meta_key'] = '_custom_priority';
    $args['orderby'] = 'meta_value_num';
    $args['order'] = 'ASC';

    return $args;
});Code language: PHP (php)

Conditional Display

Show variations based on user role:

add_filter( 'bpv_get_product_expanded_attributes', function( $attributes, $product_id ) {
    // Wholesalers see all variations
    if ( current_user_can( 'wholesale_customer' ) ) {
        $product = wc_get_product( $product_id );
        if ( $product && $product->is_type( 'variable' ) ) {
            return array_keys( $product->get_variation_attributes() );
        }
    }

    return $attributes;
}, 10, 2 );Code language: PHP (php)

Custom Variation Data

Add custom data to variations:

// Add custom class based on stock
add_filter( 'woocommerce_post_class', function( $classes, $product ) {
    if ( $product->is_type( 'variation' ) ) {
        $stock = $product->get_stock_quantity();
        if ( $stock && $stock < 5 ) {
            $classes[] = 'low-stock-variation';
        }
    }

    return $classes;
}, 10, 2 );Code language: PHP (php)

Resources

Configuration Guide – User-facing settings
Troubleshooting – Common issues
WordPress Codex – WordPress development
WooCommerce Docs – WooCommerce development

Support

For development questions:

Check existing filter/action documentation
Review the plugin source code
Test in a development environment
Contact support with specific technical questions

Remember: Always test customizations in a staging environment before deploying to production!

Developer Usage

Architecture Overview

Available Filters

bpv_enable_variation_expansion

bpv_get_global_expanded_attributes

bpv_get_product_expanded_attributes

bpv_variation_query_args

CSS Classes Reference

Programmatic Control

Custom Query Integration

Variation Ordering

Conditional Display

Custom Variation Data

Resources

Support

How can we improve this documentation?