OptionGrid Variation Matrix for WooCommerce

1. Requirements

The plugin declares compatibility with WooCommerce High-Performance Order Storage (HPOS) and the cart and checkout blocks.

2. Installation

Install WooCommerce first — OptionGrid Variation Matrix will not activate without it.

From the WordPress admin

1. Go to Plugins → Add New → Upload Plugin.
2. Choose optiongrid-variation-matrix.zip and select Install Now.
3. Select Activate Plugin.

By FTP

1. Unzip optiongrid-variation-matrix.zip.
2. Upload the optiongrid-variation-matrix folder to /wp-content/plugins/.
3. Activate the plugin from the Plugins screen.

3. Quick start

1. Edit a variable product that already has variations.
2. In the Product data panel, open the Variation Matrix tab.
3. Tick Enable Variation Matrix.
4. Choose a Layout Type and the details you want to show.
5. Select Update, then view the product on the front end.

The standard WooCommerce attribute dropdowns are replaced by the matrix. Customers type quantities next to the variations they want and select Add Selected to Cart once.

4. Layouts

5. Pro version

OptionGrid Variation Matrix Pro adds the Table layout, with one row per variation and a column for each attribute, and a live Order Totals bar showing the total items, weight and price of the quantities entered. The bar sits above the Add Selected to Cart button, and each figure can be switched on or off per product.

Pro shares its product settings, options and theme template overrides with the free version, and deactivates the free version automatically when it is activated, so nothing needs reconfiguring. It is available from wpintegrate.com.

6. Product settings

All settings below live in the Variation Matrix tab of the Product data panel and apply to that product only.

Stock and quantity handling

• Quantity fields are limited by each variation's available stock and its minimum and maximum purchase quantity. The minimum is enforced on the field and again when adding to the cart.
• Out of stock variations cannot be ordered and their quantity field is disabled or hidden.
• Backorders are permitted when WooCommerce is configured to allow them.
• The low stock threshold follows WooCommerce → Settings → Products → Inventory.
• A single request may add up to 100 different variations to the cart.

7. Global settings

Go to WooCommerce → Variation Matrix, or use the Settings link on the plugin's row on the Plugins screen. These options apply to every product that uses a variation layout.

General

Heading & Text

Controls the heading and the line of text shown above the variations.

Each field is resolved independently, in this order:

1. The product's own Heading or Intro Text, from its Variation Matrix tab.
2. The site wide value set here.
3. The built-in default for the layout being drawn.

The built-in defaults are:

Basic inline formatting such as <strong> and <a> is allowed in both fields, up to 500 characters. In the intro text of the matrix layout you can also use two placeholders:

Styling

Decides whether the plugin styles the layouts itself or leaves that to your theme.

8. Template overrides

Every layout is a template file you can override from your theme. Copy the file you want to change from:

wp-content/plugins/optiongrid-variation-matrix/public/templates/

into a wc-variation-matrix folder in your child theme:

wp-content/themes/your-child-theme/wc-variation-matrix/wcvm-variation-matrix-grid.php
wp-content/themes/your-child-theme/wc-variation-matrix/wcvm-variation-matrix-matrix.php

The child theme is checked first, then the parent theme, then the plugin.

Variables available in a template

Keys in $settings

Keys in each entry of $variations

9. Styling

All CSS classes are prefixed with wcvm-, so nothing collides with your theme. Which stylesheet loads depends on the Stylesheet setting described in Global settings:

Colour and size tokens

Every colour, size and radius in the plugin stylesheet comes from a CSS custom property declared on .wcvm-variation-matrix. The settings screen writes your values into an inline block that redeclares the same properties, which is why no rule in the stylesheet needs a hard coded colour — and why you can override any of them yourself:

.wcvm-variation-matrix {
    --wcvm-accent: #0a5c36;          /* buttons, focus rings, selected cells */
    --wcvm-accent-rgb: 10, 92, 54;   /* the same colour as an RGB triplet    */
    --wcvm-accent-contrast: #ffffff; /* text drawn on the accent colour      */
    --wcvm-text: #1f2937;
    --wcvm-muted: #6b7280;
    --wcvm-border: #e5e7eb;
    --wcvm-head-bg: #f8fafc;
    --wcvm-surface: #ffffff;
    --wcvm-font-size: 14px;
    --wcvm-radius: 8px;
}

Set --wcvm-accent-rgb alongside --wcvm-accent: the translucent focus rings and selected-cell tints are built from it.

Two further tokens are not exposed in the settings screen, but you can set them yourself:

Status colours use --wcvm-success, --wcvm-warning and --wcvm-danger, each with a matching -bg variant.

Adding your own rules

Do not edit the plugin stylesheet directly — your changes would be lost on update. Add your rules to your child theme stylesheet or the Additional CSS panel of the WordPress Customizer or Site Editor, and use the per-product Custom CSS Class setting to target one product:

/* With "my-wholesale-grid" set as the custom CSS class */
.my-wholesale-grid .wcvm-grid-item {
    border-color: #0a5c36;
}

Useful classes

Grid columns

The grid reads two CSS custom properties, so you can override them from your own stylesheet:

.wcvm-grid {
    --wcvm-columns: 4;   /* columns when there is room for them */
    --wcvm-gap: 24px;
}

The grid shows exactly the number of columns you configure. It drops to fewer only when the container it sits in is too narrow to give each card roughly 150px, stepping down at container widths of 1000px, 830px, 660px, 490px and 320px. The measurement is of the container, not the browser window, because WooCommerce usually places the product summary beside the gallery: on a 900px screen that column can be as narrow as 250px, which a window-width rule would never notice.

This uses CSS container queries. Browsers without them (Chrome before 105, Safari before 16, Firefox before 110) fall back to fitting as many 150px cards as the row allows.

Wide layouts

The matrix layout scrolls sideways inside its own container rather than squashing its columns. It keeps its attribute column pinned to the left edge, so the row labels stay visible while the rest scrolls.

10. Hooks & filters

Actions

Filters

Examples

Force the matrix layout for every product in one category:

add_filter( 'wcvm_product_settings', function ( $settings, $product_id ) {
    if ( has_term( 'clothing', 'product_cat', $product_id ) ) {
        $settings['layout'] = 'matrix';
    }

    return $settings;
}, 10, 2 );

Hide the matrix from logged out visitors:

add_filter( 'wcvm_is_enabled_for_product', function ( $enabled ) {
    return is_user_logged_in() ? $enabled : false;
} );

JavaScript

The front-end script exposes window.WCVM and triggers wcvm_cart_updated on document.body after a successful add to cart:

jQuery( document.body ).on( 'wcvm_cart_updated', function ( event, data ) {
    console.log( 'Cart now holds', data.cart_count, 'items' );
} );

11. Troubleshooting

The matrix is not showing on the product page

• Confirm the product type is Variable product and that it has at least one published, purchasable variation.
• Confirm Enable Variation Matrix is ticked and the product has been updated.
• Sign in as an administrator and reload the product page — if something is blocking the matrix, an explanatory message is shown to users who can edit products.

Attribute values show as slugs, such as "dark-blue"

The plugin resolves term names from your attribute taxonomies, so this normally points at a stale cache. Clear any page or object cache and reload. If it persists, check that the attribute terms still exist under Products → Attributes.

Add to cart does nothing, or reports a security failure

This is almost always full page caching serving a stale security token to logged out visitors. Exclude product pages from your page cache, or configure the cache to skip pages containing a WooCommerce cart form.

The layout looks wrong in my theme

Some themes style tables and buttons aggressively. First try WooCommerce → Variation Matrix → Styling and set Stylesheet to Minimal, which keeps the layout working but hands every colour, border and font back to your theme. If your theme styles the matrix completely, choose Theme styling. Otherwise add your own overrides in the child theme using the classes listed in Styling, or copy the template into your theme and adjust the markup.

My colours are not being applied

The colour and typography options only apply in Plugin styling mode. In Minimal and Theme styling the plugin does not draw those colours at all, so the fields are shown dimmed on the settings screen. Your saved values are kept and used again when you switch back.

I changed the heading but the product still shows the old text

A per-product Heading or Intro Text on the Variation Matrix tab always wins over the site wide setting. Clear the product field to fall back to the site wide value. If nothing changes at all, clear any page cache.

My changes to the layout are not appearing

If you have copied a template into your theme, that copy is used instead of the plugin's own and will not gain new features until you recopy it. Check wp-content/themes/your-theme/wc-variation-matrix/ for old copies.

Mini cart does not update

The plugin refreshes the standard WooCommerce cart fragments. If your theme uses a custom mini cart it may listen for a different event — hook wcvm_cart_updated or added_to_cart and refresh it yourself.

A conflict with another plugin

Deactivate other plugins one at a time and switch temporarily to Storefront to identify the source, then get in touch with the details.

12. Uninstalling

Deactivating the plugin never deletes anything — your product settings are preserved and reappear when you reactivate.

Data is only removed when both of the following are true:

1. Delete Data on Uninstall is set to Yes under WooCommerce → Variation Matrix.
2. The plugin is deleted from the Plugins screen, not merely deactivated.

When both apply, all plugin options and every _wcvm_* product setting are permanently removed. On a multisite network this runs for each site.

13. Changelog

1.0.0

• Initial release.

14. Support

When reporting a problem, please include your WordPress version, your WooCommerce version, your PHP version, your active theme, and the steps that reproduce it. A link to an affected product page helps a great deal.

Visit plugins.wpintegrate.com/contact-us to get in touch.