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.
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
| Attribute | What it does | Make 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-count | The element’s text becomes the live cart quantity. | Render 0 as its contents |
| data-joomni-wishlist-count | The 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:
| Attribute | Required | Meaning |
|---|---|---|
| data-joomni-product-id | yes | The product id. Missing, the click is ignored. |
| data-joomni-title | yes | The cart line name. Escape it. |
| data-joomni-price | yes | Display price for the cart line. The order total is decided by the server. |
| data-joomni-variant-id | no | Which variant to add. Omit it on a single-variant product; it is required for a real choice. |
| data-joomni-variant-title | no | The variant’s name (“M / Blush”), shown on the cart line. |
| data-joomni-has-variants | no | "true" opens the quick-add picker, "false" adds straight away. Omitted, the storefront looks the product up once to decide. |
| data-joomni-handle | no | Lets the cart line link back to the product. |
| data-joomni-image | no | Thumbnail for the cart line. |
| data-joomni-quantity-from | no | Id 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
| Rule | Why |
|---|---|
| Always give the element a real href | It 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 CSS | Count 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].
| Attribute | Value |
|---|---|
| data-carousel-desktop · -tablet · -mobile | Slides per view: a number, a fraction like 1.2, or "auto". |
| data-carousel-gap | Space between slides, in px. |
| data-carousel-loop | "true" to loop. |
| data-carousel-autoplay | Milliseconds between slides. Leave it off for no autoplay. |
| data-carousel-speed | Transition length in ms. |
| data-carousel-effect | slide, fade, coverflow or cards. |
| data-carousel-centered · -free | "true" to centre the active slide / allow free scrolling. |
| data-carousel-pagination | bullets, 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. |
Forms
data-joomni-action="lead-submit" on a <form> sends it to the store's Leads inbox. It has its own page: Contact forms.
Related guides