LiquidStorefront Widgets

Storefront Widgets

The cart, search, saved items, contact forms and carousels need state and behaviour that a template cannot carry. The storefront already has them, and a template opts in with a data-joomni attribute. You write no JavaScript, and the attribute does nothing on its own.

Try the widgets

Click Add to cart, Search or Cart in the preview. There is no store behind the playground, so it tells you what would have happened.

Cart and search widgets
Playground
Loading editor…

Runs in your browser on sample data: the same engine and filters as the storefront. Widgets such as add to cart are simulated: clicking one shows what would happen on a store.

All widgets

AttributeWhat it doesMake it degrade
data-joomni-action="cart-open"Opens the cart drawer.Put it on a link to /cart
data-joomni-action="search-open"Opens the live product search overlay.Put it on a link to /search
data-joomni-action="wishlist-open"Opens the saved-items drawer.Put it on a link to /account
data-joomni-action="cart-add"Adds the product (or the named variant) to the cart. With no data-joomni-variant-id, a product with variants opens the quick-add picker instead of being added blind.Put it on a link to the product
data-joomni-action="quick-add"Always opens the quick-add variant picker for the product.Put it on a link to the product
data-joomni-action="cart-close" · "quick-add-close"Overlay templates: closes the cart drawer or quick add. On a real link it closes and the link is still followed.href="#" or the page it should go to
data-joomni-action="cart-qty-inc" · "cart-qty-dec" · "cart-remove"Cart drawer template: changes or removes the line named by data-joomni-line="{{ item.key }}".Put it on a link to /cart
data-joomni-action="wishlist-add"Saves or unsaves the product.Put it on a link to the product
data-joomni-action="lead-submit"On a <form>: sends it to the store’s Leads inbox.Give the form a real action="/contact"
data-joomni-cart-countThe element’s text becomes the live cart quantity.Render 0 as its contents
data-joomni-wishlist-countThe element’s text becomes the live saved-items count.Render 0 as its contents
data-joomni-carousel="<section id>"Mounts a real Swiper carousel on .swiper > .swiper-wrapper > .swiper-slide markup inside. Options come from data-carousel-* attributes (below). data-joomni-carousel-ready is set once mounted.Style the wrapper as a scroll-snap row until [data-joomni-carousel-ready] appears

What cart-add reads

cart-add, quick-add and wishlist-add carry the product with them in these attributes:

AttributeRequiredMeaning
data-joomni-product-idyesThe product id. Missing, the click is ignored.
data-joomni-titleyesThe cart line name. Escape it.
data-joomni-priceyesDisplay price for the cart line. The order total is decided by the server.
data-joomni-variant-idnoWhich variant to add. Omit it on a single-variant product; it is required for a real choice.
data-joomni-variant-titlenoThe variant’s name (“M / Blush”), shown on the cart line.
data-joomni-has-variantsno"true" opens the quick-add picker, "false" adds straight away. Omitted, the storefront looks the product up once to decide.
data-joomni-handlenoLets the cart line link back to the product.
data-joomni-imagenoThumbnail for the cart line.
data-joomni-quantity-fromnoId of a <select> or <input type="number"> to read the quantity from. 1–99; anything unreadable is 1.

Prices come from the server

data-joomni-price is only what the cart line shows. The order total is always worked out from the catalogue when the order is placed, so a wrong attribute cannot change what a shopper pays.

Two rules

RuleWhy
Always give the element a real hrefIt is what a visitor gets before the page has loaded its scripts, with scripts turned off, and on a cmd-click. None of those are intercepted.
Hide a zero count with CSSCount elements also get data-empty="true|false": [data-joomni-cart-count][data-empty="true"] { display: none }

Carousels

data-joomni-carousel mounts a real Swiper carousel (arrows, dots, loop, autoplay) on standard Swiper markup. Until it mounts (and for visitors with scripts off), your fallback CSS shows instead, so key it on the absence of [data-joomni-carousel-ready].

Carousel with fallbackliquid
{%- assign uid = section.id -%}
<style>
/* Fallback until the carousel mounts: a swipeable row. */
.cr-{{ uid }}:not([data-joomni-carousel-ready]) .swiper-wrapper { display: flex; gap: 16px; overflow-x: auto; scroll-snap-type: x mandatory; }
.cr-{{ uid }}:not([data-joomni-carousel-ready]) .swiper-slide { flex: 0 0 45%; scroll-snap-align: start; }
.cr-{{ uid }} img { width: 100%; aspect-ratio: 4/5; object-fit: cover; border-radius: var(--radius); }
</style>
<div class="cr-{{ uid }} swiper" style="padding: 24px;"
data-joomni-carousel="{{ uid }}"
data-carousel-desktop="3" data-carousel-tablet="2.2" data-carousel-mobile="1.2"
data-carousel-gap="16" data-carousel-loop="true" data-carousel-pagination="bullets">
<div class="swiper-wrapper">
{%- for item in products limit: 6 -%}
<div class="swiper-slide">
<a href="{{ item.url }}"><img src="{{ item.featured_image | image_url: 600 }}" alt="{{ item.title | escape }}"></a>
</div>
{%- endfor -%}
</div>
<div class="swiper-pagination"></div>
</div>
AttributeValue
data-carousel-desktop · -tablet · -mobileSlides per view: a number, a fraction like 1.2, or "auto".
data-carousel-gapSpace between slides, in px.
data-carousel-loop"true" to loop.
data-carousel-autoplayMilliseconds between slides. Leave it off for no autoplay.
data-carousel-speedTransition length in ms.
data-carousel-effectslide, fade, coverflow or cards.
data-carousel-centered · -free"true" to centre the active slide / allow free scrolling.
data-carousel-paginationbullets, dynamic, progressbar or fraction. Needs a .swiper-pagination inside.
data-joomni-carousel-nav="<section id>"On a sibling element holding .swiper-button-prev / -next, for arrows outside the carousel.
Arrows outside the carouselliquid
<div class="swiper" data-joomni-carousel="{{ section.id }}">…</div>
<div data-joomni-carousel-nav="{{ section.id }}">
<button class="swiper-button-prev" aria-label="Previous"></button>
<button class="swiper-button-next" aria-label="Next"></button>
</div>

Forms

data-joomni-action="lead-submit" on a <form> sends it to the store's Leads inbox. It has its own page: Contact forms.

Still stuck? Our team reads every message.

Need help?