State & Display

Automatic State Sync

All elements displaying cart data update automatically when the cart changes — no extra configuration needed:

<span data-next-display="cart.total">$0.00</span>
<span data-next-display="cart.totalQuantity">0</span>
<div data-next-show="cart.hasItems">Cart has items!</div>

CSS State Classes

Elements automatically receive CSS classes based on cart state.

Toggle buttons:

<button data-next-toggle data-next-package-id="5">
  <!-- Gets .next-in-cart when item is in cart -->
  <!-- Gets .next-active when toggled on -->
  Add Item
</button>

Containers:

<div data-next-package-id="5">
  <!-- Gets .next-in-cart when package is in cart -->
  <button data-next-toggle>Toggle</button>
  <span>Product Info</span>
</div>

Selector cards:

<div data-next-selector-card data-next-package-id="1">
  <!-- Gets .next-selected when selected -->
  Package Option
</div>

Use these classes in CSS to style selected, active, and in-cart states:

.next-selected {
  border: 2px solid blue;
  background: #f0f0ff;
}

.next-in-cart {
  opacity: 0.6;
}

button.next-active {
  background: green;
  color: white;
}

See Reference → CSS for the full list of state classes.

Conditional Display

Show or hide elements based on cart state using data-next-show or data-next-hide:

<!-- Cart status -->
<div data-next-show="cart.isEmpty">Your cart is empty</div>
<div data-next-show="cart.hasItems">
  You have <span data-next-display="cart.totalQuantity">0</span> items
</div>

<!-- Specific item checks -->
<div data-next-show="cart.hasItem(2)">Package 2 is in your cart</div>

<!-- Value-based conditions -->
<div data-next-show="cart.total > 100">Free shipping unlocked!</div>

See Reference → Attributes for all supported expressions.

Force Package ID

The forcePackageId parameter pre-populates the cart with specific packages on page load. Useful for direct marketing links, quick-buy buttons, and A/B testing.

Important: forcePackageId is processed during SDK initialization. To use it programmatically, either set it before the page loads or reload after setting it.

Format

Format	Example	Result
Single package	`"1"`	Package 1, qty 1
Package + quantity	`"1:3"`	Package 1, qty 3
Multiple packages	`"1:2,3:1,5:3"`	Three packages with quantities

URL Parameter

https://yoursite.com/?forcePackageId=1
https://yoursite.com/?forcePackageId=1:3
https://yoursite.com/?forcePackageId=1:2,3:1,5:3

Programmatic Usage

// Set before SDK loads
window.nextConfig = window.nextConfig || {};
window.nextConfig.forcePackageId = "1:2,3:1";

// Or set via URL parameter API then reload
next.setParam('forcePackageId', '1:2,3:1');
window.location.reload();

Use Cases

Direct marketing links:

<a href="/checkout?forcePackageId=5:1">Buy Now – Special Offer</a>

Quick-buy buttons:

<a href="/checkout?forcePackageId=2:3">Buy 3× Package</a>

A/B testing:

<a href="/?forcePackageId=1&variant=a">Variant A</a>
<a href="/?forcePackageId=2&variant=b">Variant B</a>

Events

Listen to cart state changes with next.on(). See Reference → Events for the full event reference.

window.nextReady.push(() => {
  window.next.on('cart:updated', (data) => {
    console.log('Cart updated:', data);
  });
});

On this page