Using the bar

This page covers the day-to-day flow: letting Instigo read your goal, writing messages that convert, and restyling the bar to match your theme.

1. Let Instigo read your goal automatically

If you already run a free-shipping method (for example Free shipping over $50), leave the threshold source on Automatic. Instigo reads the smallest qualifying minimum order amount across all your zones, including the “rest of the world” zone, so the bar always matches the rule a shopper would actually hit at checkout. Change the shipping rule and the bar follows; there is nothing to keep in sync by hand.

Only methods whose requirement is A minimum order amount (or one of the combined “…and/or a coupon” options) count. A method that requires only a coupon has no amount to count down to and is skipped. If Instigo finds no qualifying method it falls back to your manual amount, so the bar keeps working while you finish configuring shipping.

Not running a free-shipping method yet? Set the source to Manual and type the amount. You can switch back to Automatic later.

2. Choose where it shows

Tick Cart page, Checkout page, or both in the General section. The cart is where most shoppers decide whether to add one more item, so it is usually the highest-impact placement. Both the classic templates and the Cart/Checkout Blocks are handled with no extra setup.

3. Write messages that motivate

Use the {amount} token in the progress message so it always shows the exact gap, formatted in your store currency:

Add {amount} more to unlock free shipping!

Then write a success message for when the goal is met. It takes no token, because there is nothing left to add:

Nice, you've earned free shipping!

Keep both short. The progress message does the persuading; the success message confirms the win. Leave either field blank to fall back to the packaged default.

How it behaves live

WooCommerce re-renders the cart and checkout totals, and Instigo’s bar with them, whenever the cart changes. The fresh server markup already carries the correct width and message, so the bar is accurate even with JavaScript disabled. Instigo’s only script is polish: it listens for WooCommerce’s updated_cart_totals, updated_checkout and updated_shipping_method events and animates the fill from its previous width to the new one so the change glides instead of snapping. The script is dependency-free (no jQuery of its own), loaded defer in the footer, and is skipped entirely under prefers-reduced-motion.

• Add items, and the bar animates toward the goal.
• Reach the goal, and the message switches to your success copy and the fill turns solid (a one-time “crossing the line” ripple plays where motion is allowed).
• Empty the cart, or have no goal configured, and the bar outputs nothing.

Theming the colours

There is no colour setting in the admin. Instead, every colour, size and radius is a CSS custom property under the --nudge-* namespace on the .nudge element, so you re-skin the bar from your theme’s stylesheet without touching markup:

.nudge {
  --nudge-pace-start: #6366f1; /* fill gradient: "on your way" */
  --nudge-pace-end:   #22c55e; /* fill gradient: "almost there" / solid when complete */
  --nudge-fill:       var(--nudge-pace-end); /* solid fallback colour */
  --nudge-track:      #e8eaed; /* unfilled track */
  --nudge-line:       #15803d; /* the etched finish-line marker */
  --nudge-success:    #15803d; /* success message + completed fill */
  --nudge-fg:         inherit; /* message text colour */
  --nudge-track-height: 0.75rem;
  --nudge-radius:     999px;
  --nudge-gap:        0.5rem;  /* space between message and track */
  --nudge-font-size:  0.95rem;
}

The bar already adapts to dark colour schemes via prefers-color-scheme, lifting the track and brightening the green so the fill stays legible. The inline placement inside the totals (.nudge--inline) uses a slightly smaller track and font automatically.

Accessibility and Core Web Vitals

The bar is a genuine role="progressbar" with aria-valuenow/aria-valuemin/aria-valuemax and an aria-label of “Progress towards free shipping”. The human-readable message sits in a polite live region (role="status", aria-live="polite", aria-atomic="true"), so a screen reader announces the whole new sentence, for example “Add $8.00 more to get free shipping”, when the cart changes, never per keystroke. The fill width is set inline so the bar is correct on first paint, and the track reserves its full height up front, so adding the bar contributes nothing to Cumulative Layout Shift.

Customising the markup

The bar is rendered from templates/progress-bar.php inside the plugin. Instigo does not load an overriding copy from your theme, so editing markup means a child plugin or a fork rather than a yourtheme/nudge/ template. For visual changes, the --nudge-* custom properties above cover colour, size and spacing without editing any PHP.

Extending Instigo

Instigo exposes a small set of hooks for developers:

• nudge/threshold (filter), the resolved free-shipping goal as a float, passed the merged settings array as the second argument. Return your own amount to override both the auto-detected and the manual figure.
• nudge/bar_context (filter), the data the template renders: context, percent, reached, message, threshold, total and remaining, with the settings array as the second argument. This is where you rewrite the message or clamp the percentage.
• nudge/bar_rendered (action), fired with that same context and the settings just before the template loads.
• nudge/booted (action), fired once with the plugin instance after Instigo starts.

There is no filter for the markup itself; the template is not theme-overridable. For everything else, configure it through WooCommerce > Instigo and restyle it with the CSS custom properties above.