Skip to content

Storefront runtime

Add the cart, product page, search, menus and sign-in to a Liquid theme with data-os attributes.

Every Paysum storefront loads the storefront runtime. It is a small script that gives all themes the same behavior: the cart, the product page, search, menus, carousels and customer sign-in. You do not write JavaScript for these. You mark elements with data-os-* attributes and the runtime does the rest.

The cart and the customer session are the same as on Paysum's own pages, so a cart filled on your theme carries over to checkout.

Cart

Add to cart from a product card

<button type="button"
  data-os-add="{{ product | cart_json | escape }}"
  data-os-href="{{ product.href }}">
  Add to cart
</button>

data-os-add takes the product as JSON from the cart_json filter. A click adds one item and opens the cart. Products with variants go to data-os-href instead, so the buyer can choose an option.

Open the cart and show the count

<button type="button"
  aria-label="Cart, 0 items"
  data-os-cart-open
  data-os-cart-badge="cart-count"
  data-os-cart-badge-max="9"
  data-os-cart-label="Cart, {n} item{s}">
  Cart
</button>
AttributeWhat it does
data-os-cart-openOpens Paysum's cart drawer. If the drawer cannot load, it goes to checkout.
data-os-cart-badge="<class>"Adds a <span class="<class>"> with the item count while the cart has items.
data-os-cart-badge-maxThe highest number shown before +. Default 99.
data-os-cart-labelThe button's accessible label. {n} is the count, {s} adds an s when the count is not 1.
data-os-cart-countAny element: its text becomes the count, or empty at zero. Format it with data-os-format="{n} items".

Product page

Wrap the buying area of templates/product.liquid in data-os-product-page. The runtime reads the product from the page and keeps the price, quantity and stock in step with the buyer's choices.

<div data-os-product-page="{{ product.id }}">
  <img src="{{ page.gallery.first | default: product.image }}" alt="{{ product.title }}" data-os-gallery-main>
  {% for src in page.gallery %}
    <button type="button" data-os-gallery-thumb="{{ src }}">…</button>
  {% endfor %}

  <strong data-os-total>{{ page.price_formatted }}</strong>
  <span data-os-each hidden>{{ page.price_formatted }} each</span>

  {% for variant in product.variants %}
    <button type="button" data-os-variant="{{ variant.id }}">{{ variant.name }}</button>
  {% endfor %}

  <button type="button" data-os-qty="-1">−</button>
  <output data-os-qty-value>1</output>
  <button type="button" data-os-qty="1">+</button>

  <button type="button" data-os-buy-now data-os-label="Buy now" data-os-label-sold-out="Out of stock">Buy now</button>
  <button type="button" data-os-add-to-cart data-os-label-added="Added to cart">Add to cart</button>

  <p data-os-stock data-os-format="{n} in stock" data-os-out="Out of stock"></p>
</div>
AttributeWhat it does
data-os-product-pageThe root of the buying area.
data-os-require-variantOn the root: the buyer must pick a variant before buying.
data-os-variant="<id>"Selects that variant. The selected button gets aria-pressed="true".
data-os-unselectedShown only while no variant is selected.
data-os-qty="-1", data-os-qty="1"Decrease and increase the quantity. Plus is disabled at the stock limit.
data-os-uncappedOn the plus button: keep it enabled at the stock limit. The quantity is still limited.
data-os-qty-valueShows the quantity.
data-os-totalShows price × quantity.
data-os-eachShows the unit price when the quantity is more than 1. Format with data-os-format="{price} each".
data-os-buy-nowGoes straight to checkout with the selection. Labels: data-os-label, data-os-label-sold-out, data-os-label-choose (while a variant is required).
data-os-add-to-cartAdds the selection to the cart. data-os-label-added shows for 2 seconds after a click.
data-os-stockShows stock. Options: data-os-format="{n} in stock", data-os-out (sold-out text), data-os-unknown (keep visible when stock is unlimited). Gets data-out="true" when sold out.
data-os-gallery-main, data-os-gallery-thumb="<url>"A thumbnail click swaps the main image.

Search

<input type="search" data-os-search="product-grid" placeholder="Search products">
<ul id="product-grid">
  {% for product in products %}
    <li data-os-search-text="{{ product.title | downcase | escape }}">…</li>
  {% endfor %}
</ul>
<p data-os-search-empty="product-grid" hidden>No products match.</p>

data-os-search names the list's id. Items whose data-os-search-text contains the query stay visible. data-os-search-empty shows when nothing matches.

Customer sign-in

AttributeWhat it does
data-os-accountOpens the sign-in dialog, or the account page when the buyer is signed in. Its accessible label switches between Sign in and Open account. Add data-os-fixed-label to keep your own label.
data-os-account-label="My account"Text shown while signed in. The element's own text shows while signed out.

Sign-in uses the same email code flow as the account page.

Menus, panels and banners

AttributeWhat it does
data-os-menu-toggle="<id>"Opens and closes the element with that id, and sets aria-expanded.
data-os-menu-closeCloses the open menu. Links inside the menu close it too.
data-os-toggle="<id>"Shows or hides the element with that id.
data-os-dismiss="<selector>"Hides the closest ancestor that matches the selector, for example an announcement bar.
data-os-scroll="<px>:<attribute>"Sets the attribute on the element once the page scrolls past that many pixels, for example data-os-scroll="8:data-scrolled" on the header.
data-os-accordion, data-os-accordion-item, data-os-accordion-toggleOne item open at a time. The open item gets data-open, toggles get aria-expanded.

Carousels and effects

AttributeWhat it does
data-os-carouselA rotating carousel. Set the delay with data-os-carousel-interval (milliseconds). Slides cross-fade.
<canvas data-os-particles>A light particle field behind the content.

The runtime also:

  • Replaces broken product images inside data-os-product with generated product art.
  • Prefetches store pages on hover so navigation feels instant.
  • Shows the store popups set up under Marketing → Popups.
  • Loads the integrations from Integrations → App store (Google Analytics, Meta Pixel, Crisp and others).

Events

EventDirectionMeaning
paysum:cart-updatedSent by the runtime on windowThe cart changed. event.detail is the cart: a list of { product, quantity }.
paysum:customer-loginListened to by the runtimeDispatch it on window to open sign-in from your own code.
window.addEventListener('paysum:cart-updated', (event) => {
  console.log('Items in cart:', event.detail.length)
})

Next steps