View Categories

Variation Swatches Developer Reference: Hooks, Meta Keys and CSS Classes

0:00 3:21
Table of Contents

Variation Swatches developer reference #

Variation Swatches for WooCommerce – Color & Image Swatches is a small, focused plugin, so its programmatic surface is compact. This reference lists the filter it exposes, the WooCommerce hooks it attaches to, the term meta keys and attribute type keys it stores, the JavaScript events it fires, and the CSS classes it renders. Everything here is taken directly from the plugin source for version 1.2.2.

Plugin filter #

Filter Passed value Purpose
alg_wc_civs_localize Array passed to wp_localize_script() as alg_wc_civs_opt Add or change the values handed to the frontend script. The core sets only_valid_term_combinations; the Pro Select2 module adds use_select2. 
add_filter( 'alg_wc_civs_localize', function ( $data ) {
    // Force only-valid-combinations off for a specific request, for example.
    $data['only_valid_term_combinations'] = false;
    return $data;
} );

WooCommerce hooks the plugin uses #

These are standard WooCommerce hooks. Knowing where the plugin attaches helps when you need to run before or after it, or unhook it.

Hook Priority What the plugin does
product_attributes_type_selector 10 Adds the Color, Image and Label attribute types.
woocommerce_dropdown_variation_attribute_options_html 999 Wraps WooCommerce’s variation dropdown and appends the swatch markup after it.
woocommerce_product_get_gallery_image_ids 10 Pro only. Appends Image-attribute term images to a variable product’s gallery when Add images on Gallery is on.

Attribute type keys #

The three types register under these internal keys (the value stored in each attribute’s attribute_type):

  • alg_wc_civs_color
  • alg_wc_civs_image
  • alg_wc_civs_label

Term meta keys #

Meta key Stored value
alg_wc_civs_term_color_color Hex color string for a Color term
alg_wc_civs_term_image_image_id Attachment ID for an Image term (used on the frontend and the gallery)
alg_wc_civs_term_label_label Text string for a Label term 
// Read a term's swatch color.
$hex = get_term_meta( $term_id, 'alg_wc_civs_term_color_color', true );

// Set an image term's swatch programmatically.
update_term_meta( $term_id, 'alg_wc_civs_term_image_image_id', $attachment_id );

Helper function and instance #

The main core instance is available through a global helper:

$civs  = color_or_image_variation_swatches_for_wc();
$admin = $civs->get_admin();          // Alg_WC_CIVS_Admin_Types
$types = $admin->wc_attribute_types;  // array of type key => label

Option keys #

Every setting is a standard WordPress option, readable with get_option():

  • alg_wc_civs_enable (default yes)
  • alg_wc_civs_scripts_on_product_page (default yes)
  • alg_wc_civs_possible_combinations (Pro, default yes)
  • alg_wc_civs_add_images_on_gal (Pro, default yes)
  • alg_wc_civs_use_select_2 (Pro, default no)
  • alg_wc_civs_enqueue_select_2 (Pro, default yes)

JavaScript events #

The frontend script exposes its object and fires events you can listen for:

Event (on body) Fires when
alg_wc_civs The script has initialized. The event’s obj property is the plugin’s JS object.
alg_wc_civs_term_click A swatch becomes active. The event carries term, select and active. 
jQuery( 'body' ).on( 'alg_wc_civs_term_click', function ( e ) {
    if ( e.active ) {
        console.log( 'Selected term element:', e.term );
    }
} );

CSS classes #

For styling, the swatch markup uses .alg-wc-civs-attribute (container) and .alg-wc-civs-term with a .color, .image or .label modifier, plus .active and .disabled states. The selected-swatch underline (Pro) is .alg-wc-civs-term-pointer. See How to change the size and shape of variation swatches for ready-to-use snippets.

Need a hand? #

Our team answers every ticket on the Variation Swatches support forum.