Display Attributes

Display attributes bind HTML elements to live data that updates automatically when state changes.

data-next-display

The primary attribute for showing dynamic values from cart, campaign, and order data.

Basic Usage

<!-- Cart totals -->
<span data-next-display="cart.total">$0.00</span>
<span data-next-display="cart.subtotal">$0.00</span>
<span data-next-display="cart.shipping">$0.00</span>
<span data-next-display="cart.tax">$0.00</span>
<span data-next-display="cart.discount">$0.00</span>

<!-- Cart quantities -->
<span data-next-display="cart.totalQuantity">0</span>
<span data-next-display="cart.itemCount">0</span>

<!-- Package data -->
<span data-next-display="package.123.price">$0.00</span>
<span data-next-display="package.123.name">Loading...</span>
<span data-next-display="package.123.description">Loading...</span>

Display Paths

Path	Description	Example Output
cart.total	Total cart value	”$99.99”
cart.subtotal	Subtotal before shipping/tax	”$89.99”
cart.shipping	Shipping cost	”$10.00”
cart.tax	Tax amount	”$8.00”
cart.discount	Discount amount	”-$10.00”
cart.totalQuantity	Total items in cart	”5”
cart.itemCount	Unique items in cart	”3”
cart.isEmpty	Cart empty state	”true” or “false”
package.[id].price	Package price	”$29.99”
package.[id].name	Package display name	”Premium Bundle”
package.[id].description	Package description	”Includes everything…”
package.[id].savings	Discount amount	”$10.00”
package.[id].quantity	Quantity in cart	”2”
campaign.name	Campaign name	”Summer Sale”
campaign.currency	Active currency	”USD”
order.total	Order total	”$99.99”
order.refId	Order reference	”ORD-12345”
profile.active	Active profile	”premium”

Formatting Options

Use data-format to control how values are displayed:

<!-- Currency formatting (default) -->
<span data-next-display="cart.total"
      data-format="currency">
  $0.00
</span>

<!-- Number only -->
<span data-next-display="cart.total"
      data-format="number">
  0.00
</span>

<!-- Integer (no decimals) -->
<span data-next-display="cart.totalQuantity"
      data-format="integer">
  0
</span>

<!-- Percentage -->
<span data-next-display="cart.discountPercent"
      data-format="percentage">
  0%
</span>

<!-- Hide zero cents -->
<span data-next-display="package.123.price"
      data-format="currency"
      data-hide-zero-cents="true">
  $100
</span>

Mathematical Operations

<!-- Divide by value -->
<span data-next-display="cart.total"
      data-divide-by="100">
  0.99
</span>

<!-- Multiply by value -->
<span data-next-display="cart.itemCount"
      data-multiply-by="10">
  30
</span>

<!-- Calculate savings -->
<span data-next-display="package.123.originalPrice"
      data-subtract="package.123.price">
  $20.00
</span>

Conditional Display

data-next-show

Show element when condition is true:

<!-- Show when cart has items -->
<div data-next-show="cart.isEmpty === false">
  Your cart has items!
</div>

<!-- Show when specific item is in cart -->
<div data-next-show="cart.hasItem(123)">
  Premium package selected
</div>

<!-- Show when total exceeds threshold -->
<div data-next-show="cart.total > 100">
  Free shipping unlocked!
</div>

<!-- Complex conditions -->
<div data-next-show="cart.totalQuantity >= 3 && cart.total > 50">
  Bulk discount applied!
</div>

data-next-hide

Hide element when condition is true (inverse of show):

<!-- Hide when cart is empty -->
<button data-next-hide="cart.isEmpty">
  Proceed to Checkout
</button>

<!-- Hide when item already in cart -->
<button data-next-hide="cart.hasItem(123)">
  Add to Cart
</button>

<!-- Hide below minimum order -->
<div data-next-hide="cart.total < 25">
  Checkout available
</div>

data-hide-if-zero

Hide element when displayed value is zero:

<!-- Hide if no discount -->
<div data-next-display="cart.discount"
     data-hide-if-zero="true">
  Discount: <span>$0.00</span>
</div>

<!-- Hide if no shipping -->
<div data-next-display="cart.shipping"
     data-hide-if-zero="true">
  Shipping: <span>$0.00</span>
</div>

data-hide-if-false

Hide element when value is false:

<div data-next-display="cart.hasDiscount"
     data-hide-if-false="true">
  Discount applied!
</div>

Profile-Based Display

Show/hide content based on active profile:

<!-- Show for specific profile -->
<div data-next-show-if-profile="premium">
  Premium member pricing
</div>

<!-- Hide for specific profile -->
<div data-next-hide-if-profile="premium">
  Upgrade to premium for better prices
</div>

<!-- Multiple profiles -->
<div data-next-show-if-profile="vip,premium,gold">
  Member exclusive content
</div>

Timer Display

data-next-timer

Display countdown timers:

<!-- Basic timer (5 minutes) -->
<div data-next-timer="true"
     data-duration="300">
  05:00
</div>

<!-- Timer with persistence -->
<div data-next-timer="true"
     data-duration="3600"
     data-persistence-id="sale-timer"
     data-format="hh:mm:ss">
  01:00:00
</div>

<!-- Timer with custom display -->
<div data-next-timer="true"
     data-duration="86400"
     data-format="dd:hh:mm:ss">
  1d 00:00:00
</div>

Timer format options:

• mm:ss - Minutes and seconds
• hh:mm:ss - Hours, minutes, seconds
• dd:hh:mm:ss - Days, hours, minutes, seconds
• auto - Automatic formatting based on duration

Complex Display Patterns

Cart Summary

<div class="cart-summary">
  <!-- Cart count badge -->
  <span data-next-display="cart.totalQuantity"
        data-hide-if-zero="true"
        class="badge">0</span>

  <!-- Empty cart message -->
  <div data-next-show="cart.isEmpty">
    Your cart is empty
  </div>

  <!-- Cart items -->
  <div data-next-hide="cart.isEmpty">
    <div>Items: <span data-next-display="cart.itemCount">0</span></div>
    <div>Subtotal: <span data-next-display="cart.subtotal">$0.00</span></div>

    <!-- Conditional shipping -->
    <div data-next-display="cart.shipping"
         data-hide-if-zero="true">
      Shipping: <span>$0.00</span>
    </div>

    <!-- Conditional discount -->
    <div data-next-display="cart.discount"
         data-hide-if-zero="true">
      Discount: <span>$0.00</span>
    </div>

    <div>Total: <span data-next-display="cart.total">$0.00</span></div>
  </div>
</div>

Product Card with Dynamic Pricing

<div class="product-card" data-package-id="123">
  <!-- Dynamic price -->
  <div class="price">
    <span data-next-display="package.123.price"
          data-format="currency"
          data-hide-zero-cents="true">$0</span>
  </div>

  <!-- Original price with strikethrough -->
  <div data-next-show="package.123.hasDiscount">
    <s data-next-display="package.123.originalPrice">$0.00</s>
    <span data-next-display="package.123.savings">Save $0</span>
  </div>

  <!-- Stock status -->
  <div data-next-show="package.123.inStock === false"
       class="out-of-stock">
    Out of Stock
  </div>

  <!-- In cart indicator -->
  <div data-next-show="cart.hasItem(123)">
    <span data-next-display="package.123.quantity">0</span> in cart
  </div>
</div>

Order Confirmation

<div data-next-show="order.exists">
  <h2>Order Confirmed!</h2>
  <p>Order ID: <span data-next-display="order.refId">-</span></p>
  <p>Total: <span data-next-display="order.total">$0.00</span></p>

  <!-- Order items -->
  <div data-next-order-items="true">
    <!-- SDK will populate this -->
  </div>
</div>

Cart Items Template Variables

The data-next-cart-items renderer uses template variables to display cart item data. All variables use the {item.*} syntax.

Basic Item Properties

<div data-next-cart-items>
  <div class="cart-item">
    <h4>{item.name}</h4>
    <p>SKU: {item.sku}</p>
    <p>Quantity: {item.quantity}</p>
    <img src="{item.image}" alt="{item.name}">
  </div>
</div>

Variable	Description	Example
{item.id}	Unique cart item ID	Auto-generated
{item.packageId}	Package ID	”123”
{item.name}	Product name	”Grounded Sheets”
{item.title}	Product title (alias)	“Grounded Sheets”
{item.quantity}	Quantity in cart	”2”
{item.image}	Product image URL	”https://…”
{item.sku}	Product SKU	”GRS-001”
{item.frequency}	Purchase frequency	”One time” or “Every month”

Variant Properties

Display product variant information:

<div data-next-cart-items>
  <div class="cart-item">
    <h4>{item.productName}</h4>
    <p class="variant">{item.variantName}</p>
    <p class="attributes">{item.variantAttributesFormatted}</p>

    <!-- Individual variant attributes -->
    <span class="color">Color: {item.variantColor}</span>
    <span class="size">Size: {item.variantSize}</span>
  </div>
</div>

Variable	Description	Example
{item.productId}	Base product ID	Auto-generated
{item.productName}	Base product name	”Grounded Sheets”
{item.variantId}	Variant ID	Auto-generated
{item.variantName}	Full variant name	”Grounded Sheets - Obsidian Grey / Twin”
{item.variantSku}	Variant SKU	”BE-GRS-TWN-GR”
{item.variantAttributes}	Raw array of variant attributes	For JSON output
{item.variantAttributesFormatted}	Formatted attributes	”Color: Obsidian Grey, Size: Twin”
{item.variantAttributesList}	HTML formatted attributes	<span>Color: Grey</span>
{item.variantColor}	Color value (dynamic)	“Obsidian Grey”
{item.variantSize}	Size value (dynamic)	“Twin”
{item.variant.color}	Color (dot notation)	“Obsidian Grey”
{item.variant.size}	Size (dot notation)	“Twin”
{item.variant_color}	Color (underscore)	“Obsidian Grey”
{item.variant_size}	Size (underscore)	“Twin”

Individual variant attributes are dynamically generated for all variant attribute codes.

Pricing Variables

<div data-next-cart-items>
  <div class="cart-item">
    <p class="price">{item.price}</p>
    <p class="unit-price">{item.unitPrice} each</p>
    <p class="line-total">Total: {item.lineTotal}</p>

    <!-- Show original price if on sale -->
    <s class="{item.showCompare}">{item.comparePrice}</s>
  </div>
</div>

Variable	Description	Type
{item.price}	Package price	Currency
{item.unitPrice}	Price per unit	Currency
{item.comparePrice}	Original price before discount	Currency
{item.unitComparePrice}	Original unit price	Currency
{item.lineTotal}	Line total (price × quantity)	Currency
{item.lineCompare}	Original line total	Currency
{item.recurringPrice}	Subscription price	Currency

Savings Variables

<div data-next-cart-items>
  <div class="cart-item {item.showSavings}">
    <p class="savings">
      Save {item.savingsAmount} ({item.savingsPct}%)
    </p>
  </div>
</div>

Variable	Description	Type
{item.savingsAmount}	Total savings	Currency
{item.unitSavings}	Per-unit savings	Currency
{item.savingsPct}	Savings percentage	Percentage
{item.packageSavings}	Package-level savings	Currency
{item.packageSavingsPct}	Package savings %	Percentage

Package Details

<div data-next-cart-items>
  <div class="cart-item">
    <p>Package Price: {item.packagePrice}</p>
    <p>Package Total: {item.packagePriceTotal}</p>
    <p>Package Retail: {item.packageRetailPrice}</p>
    <p>Units in Package: {item.packageQty}</p>
  </div>
</div>

Variable	Description	Type
{item.packagePrice}	Base package price	Currency
{item.packagePriceTotal}	Package total price	Currency
{item.packageRetailPrice}	Package retail price	Currency
{item.packageRetailTotal}	Package retail total	Currency
{item.packageQty}	Quantity in package	Number

Coupon Discount Variables

<div data-next-cart-items>
  <div class="cart-item {item.showDiscount}">
    <p>Price: <s>{item.price}</s> {item.discountedPrice}</p>
    <p class="discount">Coupon: -{item.discountAmount}</p>
    <p class="final">Final: {item.finalPrice}</p>
  </div>
</div>

Variable	Description	Type
{item.discountAmount}	Coupon discount amount	Currency
{item.discountedPrice}	Price after coupon	Currency
{item.discountedLineTotal}	Line total after coupon	Currency
{item.hasDiscount}	Has coupon discount	”true” or “false”
{item.finalPrice}	Final display price	Currency
{item.finalLineTotal}	Final line total	Currency

Conditional Display Classes

Use these to show/hide elements conditionally:

<div data-next-cart-items>
  <div class="cart-item">
    <!-- Shows "show" or "hide" class -->
    <span class="{item.showCompare}">{item.comparePrice}</span>
    <span class="{item.showSavings}">Save {item.savingsAmount}</span>
    <span class="{item.showDiscount}">Coupon applied!</span>
    <span class="{item.showRecurring}">{item.frequency}</span>
  </div>
</div>

Variable	Returns	Description
{item.showCompare}	”show” or “hide”	Show compare price if has savings
{item.showSavings}	”show” or “hide”	Show savings badge
{item.showRecurring}	”show” or “hide”	Show subscription info
{item.showUnitPrice}	”show” or “hide”	Show unit price for multi-packs
{item.showDiscount}	”show” or “hide”	Show coupon discount
{item.showOriginalPrice}	”show” or “hide”	Show strikethrough price
{item.hasSavings}	”true” or “false”	Boolean for conditionals
{item.isRecurring}	”true” or “false”	Is subscription product

Cart Template Configuration

Configure cart items renderer with these attributes:

<!-- Template by ID -->
<template id="cart-item-template">
  <div class="item">{item.name} - {item.price}</div>
</template>
<div data-next-cart-items
     data-item-template-id="cart-item-template">
</div>

<!-- Empty cart message -->
<div data-next-cart-items
     data-empty-template='<p>Your cart is empty</p>'>
</div>

<!-- Group identical items -->
<div data-next-cart-items
     data-group-items>
</div>

<!-- Custom titles for packages -->
<div data-next-cart-items
     data-title-map='{"2": "Premium Package", "3": "Starter Kit"}'>
</div>

Attribute	Description	Example
data-item-template-id	Reference template by ID	"cart-item-template"
data-item-template-selector	Reference by CSS selector	"#custom-template"
data-item-template	Inline template string	'<div>{item.name}</div>'
data-empty-template	Template when cart is empty	'<p>No items</p>'
data-title-map	Map package IDs to titles (JSON)	'{"2": "Premium"}'
data-group-items	Group identical items together	Flag attribute

Raw Values for Calculations

Use .raw suffix for numeric calculations:

<div data-next-cart-items>
  <div class="cart-item">
    <!-- Calculate 10% of line total -->
    <p>Tax: ${item.lineTotal.raw * 0.1}</p>
  </div>
</div>

Variable	Description
{item.price.raw}	Numeric price value
{item.unitPrice.raw}	Numeric unit price
{item.lineTotal.raw}	Numeric line total
{item.savingsAmount.raw}	Numeric savings
{item.savingsPct.raw}	Numeric savings percentage
{item.discountAmount.raw}	Numeric discount
{item.discountedPrice.raw}	Numeric discounted price
{item.discountedLineTotal.raw}	Numeric discounted line total
{item.finalPrice.raw}	Numeric final price
{item.finalLineTotal.raw}	Numeric final line total

Package Subscription Fields

Display subscription and recurring billing information for packages.

Package ID Fields

<!-- Package reference ID -->
<span data-next-display="package.123.ref_id">Internal ID</span>

<!-- External package ID -->
<span data-next-display="package.123.external_id">External ID</span>

Property	Description	Type
package.ref_id	Internal reference ID	Number
package.external_id	External system ID	Number

Recurring Properties

<!-- Show subscription info -->
<div data-next-show="package.123.is_recurring">
  <p>Subscription Product</p>
  <p>Delivered every <span data-next-display="package.123.interval">month</span></p>
</div>

<!-- One-time purchase -->
<div data-next-show="package.123.isOneTime">
  <p>One-time purchase</p>
</div>

Property	Description	Type	Values
package.is_recurring	Is subscription product	Boolean	true/false
package.interval	Billing interval	String	”day”, “month”, null
package.interval_count	Interval count	Number	1, 2, 3, etc.
package.isRecurring	Is subscription (alias)	Boolean	true/false
package.isOneTime	Is one-time purchase	Boolean	true/false

Recurring Pricing

<!-- Recurring price -->
<span data-next-display="package.123.price_recurring">$29.99/month</span>

<!-- Total recurring price -->
<span data-next-display="package.123.price_recurring_total">$89.97</span>

Property	Description	Type
package.price_recurring	Recurring price per billing cycle	Currency
package.price_recurring_total	Total recurring price for all units	Currency

Subscription Display Example

<div class="product-card" data-package-id="123">
  <h3 data-next-display="package.123.name">Product Name</h3>

  <!-- One-time price -->
  <div data-next-show="package.123.isOneTime">
    <p class="price" data-next-display="package.123.price">$99.00</p>
    <p>One-time purchase</p>
  </div>

  <!-- Subscription price -->
  <div data-next-show="package.123.isRecurring">
    <p class="price" data-next-display="package.123.price_recurring">$29.99</p>
    <p>
      Billed every
      <span data-next-display="package.123.interval_count">1</span>
      <span data-next-display="package.123.interval">month</span>
    </p>
  </div>
</div>

Performance Tips

Efficient Selectors

<!-- ✅ Specific paths are faster -->
<span data-next-display="cart.total">$0</span>

<!-- ❌ Avoid deep nesting -->
<span data-next-display="cart.items[0].product.variations[0].price">$0</span>

Reduce Recalculations

<!-- ✅ Single display element -->
<div data-next-display="cart.summary"
     data-template="{itemCount} items - {total}">
  0 items - $0.00
</div>

<!-- ❌ Multiple elements that update together -->
<span data-next-display="cart.itemCount">0</span> items -
<span data-next-display="cart.total">$0.00</span>

Conditional Rendering

<!-- ✅ Hide parent container -->
<div data-next-show="cart.hasDiscount">
  <h3>Discounts Applied</h3>
  <span data-next-display="cart.discount">$0.00</span>
</div>

<!-- ❌ Hide multiple children individually -->
<div>
  <h3 data-next-show="cart.hasDiscount">Discounts Applied</h3>
  <span data-next-show="cart.hasDiscount"
        data-next-display="cart.discount">$0.00</span>
</div>

Fallback Content

Always provide fallback content for progressive enhancement:

<!-- Fallback for prices -->
<span data-next-display="package.123.price">
  Starting at $29.99
</span>

<!-- Fallback for availability -->
<span data-next-display="package.123.inStock">
  Check availability
</span>

<!-- Fallback for loading states -->
<span data-next-display="campaign.name">
  Loading campaign...
</span>

Debugging Display

Enable debug mode to see:

• Which elements are bound to data
• Update frequency and performance
• Data path resolution
• Formatting applied

<!-- With ?debugger=true, shows -->
<span data-next-display="cart.total"
      class="next-display-bound"
      data-display-path="cart.total"
      data-display-value="99.99"
      data-display-formatted="$99.99">
  $99.99
</span>

Related Documentation

• Actions - Interactive elements
• State Management - Conditional logic
• Events - React to data changes
• Cart Display - Complete cart UI patterns