WC Sticky Variations Documentation

Everything you need to install, configure, and customize the sticky variation bar. Covers all 15 admin settings, every exposed CSS variable, theme integration, and troubleshooting.

Overview

WC Sticky Variations adds a sticky add-to-cart bar to single variable product pages in WooCommerce. The bar appears when the customer scrolls past the native add-to-cart area and slides out of view when they scroll back up. It mirrors the customer's current variation selection in real-time — image, price, stock status, and add-to-cart button state.

The plugin is built around four hard engineering constraints: object-oriented class architecture, strict conditional loading, no AJAX or duplicate variation queries, and IntersectionObserver-based scroll detection (no scroll listeners). The result is a feature that adds zero overhead to non-variable pages and runs at 60fps on low-end mobile devices.

All configuration happens from a single tab under WooCommerce › Settings › Sticky Variations. There are fifteen settings split into three groups: General, Appearance, and Advanced.

Requirements

WordPress 6.0 or higher
WooCommerce 7.0 or higher
PHP 7.4 or higher
A theme that uses WooCommerce's standard form.variations_form markup (nearly every WooCommerce-compatible theme)

No external services, no API keys, and no third-party PHP libraries are required.

Installation

Download the plugin .zip from your Boulley Technology account. In your WordPress admin, go to Plugins › Add New › Upload Plugin, select the ZIP file, and click Install Now. After installation, click Activate.

The plugin registers a settings tab at WooCommerce › Settings › Sticky Variations. Default values are applied automatically — the sticky bar is active on every variable product page immediately after activation.

Note: The sticky bar only renders on single variable product pages. It will not appear on simple, grouped, or external products, nor on the shop, cart, or any non-product page. This is enforced at the PHP level so no scripts or styles are enqueued where they're not needed.

License Activation

After installation, activate your license to receive automatic updates and support. From the WordPress admin, navigate to WooCommerce › Settings › Sticky Variations and scroll to the bottom of the page. Paste your license key into the License field and click Activate.

Your license key was emailed to you after purchase. You can also find it in your account portal. Each license is valid for unlimited sites.

Settings Overview

The settings page is split into three sections. Every value is stored in a single autoloaded WordPress option (wc_sv_settings) so the front-end reads everything in one database query.

Changes take effect immediately on save — no cache flush required. If you use a page-caching plugin, you may need to clear its cache to see updates on already-cached product pages.

General Settings

Setting	Default	Description
Enable sticky bar	`Yes`	Master switch. Disable to hide the bar everywhere without deactivating the plugin.
Bar position	`Bottom`	Whether the bar slides up from the bottom of the viewport or down from the top. Bottom is recommended for mobile-first stores.
Show on mobile	`Yes`	Disable to hide the bar on screens narrower than 600px. Some stores prefer the native add-to-cart on small screens.
Show product image	`Yes`	Display the variation image thumbnail in the bar. Disable for a more compact layout.
Add-to-cart button label	(empty)	Override the default "Add to cart" text. Leave blank to use the default. Useful for brand voice — "Grab one", "Buy now", "Add to bag".

Appearance Settings

All color settings use the WordPress core color picker and accept hex values (#1a1a1a, #ffffff, etc.). The defaults produce a clean, neutral bar that works with most themes out of the box.

Setting	Default	Description
Background color	`#ffffff`	The bar's background fill.
Text color	`#1a1a1a`	The product title and attribute summary text color.
Border color	`#e6e6e6`	The thin border above (or below, if top-positioned) the bar.
Price color	`#1a1a1a`	The variation price text color.
Button background	`#1a1a1a`	The add-to-cart button background fill.
Button text color	`#ffffff`	The add-to-cart button label color.

Tip: For a high-contrast look, set the button background to your brand's primary color and leave the text white. Most successful conversion bars use a button color that stands out against the bar background.

Advanced Settings

Setting	Default	Description
Animation duration	`280` ms	The time the slide-in/slide-out animation takes. Range 0–1000ms. Set to 0 to disable the animation entirely.
z-index	`9990`	The CSS stacking order. The default sits above most theme chrome but below WooCommerce's blockUI overlay. Raise this if your theme overlays the bar.
Max content width	`1280` px	Limits the inner content to this width on wide screens. Set to 0 for full viewport width.

Warning: Raising z-index above WooCommerce's blockUI overlay (typically in the millions) will make the sticky bar visible during AJAX add-to-cart loading states. This is usually not desirable — the loading shroud should cover the bar so customers don't double-click.

CSS Variables

For theme developers, every themable value is exposed as a CSS custom property on #wc-sv-bar. Override these in your theme's stylesheet, the Customizer's Additional CSS box, or any plugin that injects custom CSS — no admin settings page interaction required.

#wc-sv-bar {
    --wc-sv-bg:             #ffffff;
    --wc-sv-text:           #1a1a1a;
    --wc-sv-border:         #e6e6e6;
    --wc-sv-price-color:    #1a1a1a;
    --wc-sv-button-bg:      #1a1a1a;
    --wc-sv-button-text:    #ffffff;
    --wc-sv-z-index:        9990;
    --wc-sv-anim-duration:  280ms;
    --wc-sv-max-width:      1280px;
}

Inline values from the admin settings always take precedence — they're injected as a higher-specificity inline style block. CSS variable overrides are useful when the admin settings don't expose enough control, or when you want palette consistency across themes without configuring each install.

Theme Overrides

To match your theme's existing button style, target the sticky bar's button class. The class list is intentionally specific so you don't have to fight default specificity:

/* Make the sticky CTA match your theme's primary button */
#wc-sv-bar .wc-sv-bar__add {
    border-radius: 999px;
    font-family: 'Inter', sans-serif;
    text-transform: uppercase;
    letter-spacing: 0.5px;
}

/* Adjust the bar's vertical padding */
#wc-sv-bar .wc-sv-bar__inner {
    padding: 14px 24px;
}

The full BEM-style class list:

.wc-sv-bar — the root element
.wc-sv-bar--bottom, .wc-sv-bar--top — position variants
.wc-sv-bar--no-image — applied when the image is hidden via settings
.wc-sv-bar.is-visible — applied while the bar is in view
.wc-sv-bar__inner — flex container
.wc-sv-bar__media, .wc-sv-bar__image — variation image
.wc-sv-bar__meta, .wc-sv-bar__title, .wc-sv-bar__price — product info
.wc-sv-bar__attributes — current selection summary
.wc-sv-bar__qty, .wc-sv-bar__qty-input — quantity control
.wc-sv-bar__add — the add-to-cart button

How It Works

The plugin is built from four PHP classes and a small front-end stack. Understanding how they fit together helps when debugging theme conflicts or extending behavior.

Detection & gating

On every front-end request, WC_SV_Template::is_variable_product_page() checks whether the request is for a single product (is_product()) and whether that product is of type variable. Both the asset enqueue and the markup injection are gated by this check. If either condition fails, the plugin emits nothing.

Markup injection

When the gate passes, an empty skeletal <aside id="wc-sv-bar"> is appended to the page via wp_footer. The skeleton has no prices, no titles, no attribute values, no inline JSON — every node is populated client-side. This avoids any duplicate database queries on the page load.

Scroll detection

The JavaScript creates an IntersectionObserver that watches the native form.variations_form element. When the form leaves the viewport, the observer fires and adds .is-visible to the sticky bar. When the form re-enters, the class is removed. This is far more efficient than a scroll listener and incurs zero cost when the user is idle.

Variation mirroring

WooCommerce already fires a jQuery found_variation event on the variations form whenever the user picks a matching combination of attributes. The plugin listens for this event and reads variation.image.src, variation.price_html, variation.is_in_stock, and variation.is_purchasable directly from the event payload — the same payload WC already resolved at page render. No additional AJAX calls are made.

Add-to-cart proxy

When a customer clicks the sticky add-to-cart button, the plugin syncs the quantity into WooCommerce's native quantity input and then programmatically clicks the native .single_add_to_cart_button. This means every existing WC hook, AJAX-add-to-cart fragment, validation message, and third-party plugin handler runs exactly as if the customer clicked the native button directly.

Compatibility

WC Sticky Variations has been tested with:

Themes: Storefront, Astra, Kadence, GeneratePress, OceanWP, Hello Elementor, Divi, Blocksy
Page builders: Elementor, Divi Builder, Beaver Builder, Bricks — provided the product template still includes the standard variations form
Variation swatch plugins: WooCommerce Variation Swatches (Iconic, WC Vendors, etc.) — the plugin reads from the underlying <select> values that swatch plugins update
Cart plugins: CartFlows, FunnelKit, WPC Smart Quick View — the proxy click triggers their handlers normally
Caching: WP Rocket, LiteSpeed Cache, W3 Total Cache — safe to combine; the plugin's inline CSS variables are not affected by minification

If you encounter a theme that doesn't render the standard form.variations_form markup (rare), the sticky bar will not appear because there's no form for the IntersectionObserver to watch. Contact support if you hit this — it's almost always fixable with a small selector tweak.

Performance Notes

Performance was the primary design constraint. Some specifics:

Conditional loading: No CSS, JS, or markup is enqueued on the home page, shop, cart, checkout, account, or any non-variable-product page.
Asset size: The full CSS is approximately 5KB; the JS is approximately 4KB. Both are minified-friendly (no PHP-generated content other than the inline CSS variables block).
Animation: The reveal animates only transform and opacity — both compositor-only properties. The browser doesn't trigger layout or paint during the slide.
Containment: The bar uses contain: layout paint so any reflow or repaint inside its subtree is scoped — it can't trigger a page-wide layout pass.
No scroll listeners: The IntersectionObserver fires only when the watched element crosses a threshold, not on every scroll event. CPU usage during scrolling is effectively zero.
Database: All settings are stored in a single autoloaded option, so the front-end reads them in the same query as core WP options.

Accessibility

The bar is built with accessibility in mind:

Uses a semantic <aside role="region"> with an aria-label of "Quick add to cart".
Dynamic price and attribute updates use aria-live="polite" so screen readers announce variation changes.
When hidden, the bar is fully inert: opacity: 0, pointer-events: none, and aria-hidden="true". Keyboard focus cannot enter it and mouse clicks pass through.
The quantity input has a properly-associated visually-hidden <label>.
The add-to-cart button uses disabled + aria-disabled="true" when no variation is selected.
The reveal animation honors prefers-reduced-motion — users with motion sensitivity get a brief fade instead of the slide.

Updating

Once your license is activated, WC Sticky Variations receives automatic updates through your WordPress dashboard. When a new version is released you'll see the standard plugin update notification under Plugins and on the WordPress Updates screen. Click Update Now to install.

Updates are delivered from boulleytechnology.ca/api/plugin-updates.php. They include new features, bug fixes, and security patches. Your settings persist across updates — you never need to reconfigure.

Troubleshooting

The bar isn't appearing

Check these in order:

Make sure you're on a single variable product page, not the shop, a simple product, or a custom page. The plugin doesn't load anywhere else.
Verify the master enable toggle is on in WooCommerce › Settings › Sticky Variations.
If you're on mobile, check that Show on mobile is enabled.
Scroll past the native add-to-cart form — the bar only appears when the form is out of view.
Open your browser's DevTools and look for #wc-sv-bar in the DOM. If it's there but not visible, your theme is likely setting display: none or overriding the z-index. See the next item.

The bar is in the DOM but invisible

Almost always a z-index conflict. Raise the z-index setting in Advanced until the bar sits above your theme's chrome (try 99999). If your theme uses transformed parent elements that break position: fixed, the bar should still work because it's appended to wp_footer outside the main content containers — but page builders sometimes inject content into the footer that creates a transformed wrapper. In that case, contact support with your theme/builder details.

Variation image or price doesn't update

This indicates that WooCommerce's found_variation event isn't firing on your product page. The most common cause is a variation-swatch plugin that bypasses the native form. Try temporarily disabling other variation-related plugins to isolate the conflict, then contact support — most swatch plugins fire the same event for compatibility.

The sticky button doesn't add to cart

The sticky button proxies a click to your native .single_add_to_cart_button. If the native button works but the sticky one doesn't, something is intercepting the proxied click. Check for plugins that bind to the native button with stopPropagation() or that replace it entirely after the page loads.

Caching plugins don't pick up settings changes

Settings are stored in a WordPress option and applied via inline CSS variables. If you're using a page-caching plugin (WP Rocket, LiteSpeed, etc.) you'll need to clear the page cache after changing settings to see the update on already-cached product pages. The plugin itself caches nothing — changes are live on the first uncached page load.

FAQ

Can I disable the bar on specific products?

Not from the admin UI in version 1.0. The bar is either on or off site-wide via the master enable toggle. Per-product disable is on the roadmap; if you need it now you can add a small filter to your theme's functions.php:

add_filter('pre_option_wc_sv_settings', function($value) {
    if (is_product() && get_queried_object_id() === 12345) {
        $value['enabled'] = 'no';
    }
    return $value;
});

Does it work with WooCommerce Subscriptions?

Yes — variable subscriptions are detected as variable for the purpose of WC type checks, so the bar appears normally. The subscription-specific pricing markup (e.g., "$X every month") is rendered correctly because the plugin uses WC's pre-rendered price_html.

Does it work with multilingual sites (WPML, Polylang)?

Yes. The bar's only translatable strings (the button label and ARIA labels) go through standard WordPress translation functions. WPML and Polylang both pick them up.

Can I use it with a custom add-to-cart endpoint or third-party cart plugin?

Yes, as long as that plugin still hooks into WooCommerce's .single_add_to_cart_button. Since the sticky button proxies a click to the native button, any plugin that intercepts that click will run normally. CartFlows, FunnelKit, and similar tools work without configuration.

Will it break my AMP pages?

The plugin only enqueues on standard WordPress front-end requests. If your site uses an AMP plugin that serves AMP versions of product pages on a separate URL or via content negotiation, those pages will not include the sticky bar (which is correct — AMP doesn't allow custom JS).

Support

If you run into anything that isn't covered here:

Submit a support ticket at boulleytechnology.ca/support.php
Email support at support@boulleytechnology.ca
General inquiries: info@boulleytechnology.ca
Browse all plugin documentation at boulleytechnology.ca/docs.php

License holders get priority response. We typically reply within a few hours during business hours.