Using Widgets

How to place widgets (e.g. product carousels or CMS blocks) at specific spots in your store.

Widgets (Content > Elements > Widgets) are the tool for showing dynamic or static content at precisely defined spots in the theme, without having to write layout XML yourself.

Available widget types

The exact range depends on the installed theme/modules, but common ones include: CMS Static Block (embed an existing CMS block), Catalog Products List (a product list by criteria like category or bestsellers), Catalog New Products List (recently added products), Catalog Category Link and Catalog Product Link (individual links), and Recently Viewed/Compared Products.

Setting up a widget

1. Under Add Widget, first choose the Widget Type.
2. Select the Design Theme the widget should apply to.
3. Under Storefront Properties, set a display name and sort priority.
4. Under Widget Options, define the actual content (e.g. which CMS block or which products, including filter criteria like category or count).
5. Under Layout Updates, define WHERE the widget appears: on which page type (e.g. only category pages, only the homepage), optionally narrowed further to specific categories/products, and in which layout container (e.g. "Sidebar Additional" or "Content Top").

Typical examples

A "New in stock" product carousel on the homepage, an info banner only on certain category pages, or a CMS block with opening hours in the footer. Because widgets are configured through the backend UI, they're a good way to place content without needing developer access to the theme files – though the container/block name a widget hooks into is theme-dependent and can't be freely chosen.

Inserting widgets directly into text

Besides placement via Layout Updates, there's a second, often-overlooked way: in the WYSIWYG editor of a CMS page or CMS block, the Insert Widget button opens the same selection dialog used when creating a widget instance. The chosen widget is then inserted as a placeholder directive right at the cursor position in the content – useful when a widget shouldn't sit at a fixed layout position but appear in the middle of running text (e.g. a product carousel between two paragraphs on a landing page).

Fine-grained page restriction

In the Layout Updates section of a widget instance, the Display On selector controls, depending on the chosen widget type, how precisely the display is scoped – ranging from "All Pages" and "Specified Page" to more granular options such as only anchor category pages (with subcategories) or only non-anchor category pages. Below that, a multi-select lets you narrow it further to specific categories or products. Practical tip: after saving, always check both an affected and an unaffected page – a wrongly chosen Display On option is one of the most common reasons a widget "just doesn't show up".

Ordering multiple widgets in the same spot

When several widget instances land in the same layout container (e.g. two banners in "Content Top"), the Sort Order field under Storefront Properties determines the order they're rendered in – lower values appear first. Without a deliberately set sort order, the output order depends on internal creation order, which can quickly lead to unpredictable display once multiple editors are involved.