Lists that fill themselves

You do not build a card per product. You build one card, and a list element repeats it for every product its source returns.

These elements live in the Store panel on the rail.

Two kinds of list

Product list — repeats a card per product.

Collection list — repeats a card per collection.

Both work the same way: inside sits one card template, you design it, and the storefront repeats it.

Designing the card template

Drag elements into the template as usual. The ones that know how to pull the current row's data include Product media, the title, Pricing, an add-to-cart button, and the collection equivalents (Collection title, Collection description, Collection media).

When an element sits inside the template, its Source field is locked and says why:

"Inside a repeating item, so it follows that item's product."

That is what you want. Outside a repeater, the same element lets you pick Automatic (follow the page's context) or Custom (pin one specific product).

What the list shows

Drop a Product list and it shows all products by default. To narrow it, click the collection picker — the on-canvas hint says: "Click here to choose which collections this list shows."

Pick one or several collections. Products in any selected collection appear, and child collections count too — picking a parent category takes in the branch beneath it.

If the store has no collections yet, the panel says so plainly: "No collections to show — Create collections in your store and they will show up here."

A collection is not the only source

The Source field offers four more, and each answers a different question:

• Automatic (this page) — the collection the page itself IS. On a Collection template (/collections/{collection}) the list fills with that collection's products, so one page serves every collection. Anywhere else there is no collection to read and it shows every product — the panel says so before you are surprised by it: "This page is not a Collection template, so this source shows every product."
• Featured products — the ones you ticked Featured on the product form. Its axis is the store, so it renders on any page; a home page shelf is what it is for.
• Related products — the products sharing a collection with the one the page is showing, minus that product itself. Its axis is the page, so off a product page it has nothing to work from and shows its empty state.
• The name of a relation block — a list you picked by hand, per product. See Relation blocks.

None of the last three has a fallback: nothing ticked, nothing related, nothing picked — the shelf is empty and says why, rather than grabbing a few products to fill the gap. A shelf padded with whatever was to hand, under a heading reading "Featured products", looks exactly like a working feature.

The thing that catches people: "All products" narrows too on a Collection template. It has since templates shipped; it simply never said so. The panel now tells you where you are standing: "On a Collection template this source narrows to the collection being viewed. Pick 'Automatic (this page)' to say so explicitly." Both sources give the same grid there — the second one just says what it is doing, so whoever opens the page after you does not have to guess.

Where a Collection list gets its rows

The Collection list's own Source field has three answers, and the first — which is also what it drops on — turns one page into a whole tree of categories:

• Automatic (this page's sub-collections) — the direct children of the collection the page is. Drop the list on a Collection template and you are done, with nothing to set: /collections/shirts draws the children of "Shirts", /collections/shoes draws the children of "Shoes". No page per collection.
• All collections — every collection in the store, including on a Collection template. This source does not narrow itself, unlike "All products" above. Anywhere but a Collection template it gives exactly what the automatic source gives — which is why the automatic one can afford to be the default: on every other page, a bare drop looks the same as it always did.
• Custom collections — exactly the ones you pick, in the order you drag them. Quantity does not cut this list: you chose it by hand, so nothing is dropped.

A collection with no children shows the empty state rather than falling back to every collection — the other collections sitting there look exactly as though they were inside this one.

Off a Collection template the automatic source shows every collection, and the panel says so first: "This page is not a Collection template, so this source shows every collection." It is still offered on every page for a reason: a global section does not know which page it will end up on.

Paging

The Loading mode group in the inspector holds a Mode select with four answers:

• None — the cards you asked for and nothing further. This is the default.
• Pagination — a row of page numbers under the grid.
• Load more — a button that appends the next page in place.
• Scroll more — the same append, triggered by reaching the end of the list. There is no button to press.

The thing that trips people: Quantity changes meaning. On None, Quantity is a cap — the list shows that many cards and stops. Pick any other mode and the same number becomes the page size. A "New in" shelf left at 4 with pagination on will cut your whole catalogue into pages of four; you usually want 8–12.

Only Pagination has an address. Clicking a page number changes the URL, so a shopper can bookmark it, share it, and use the Back button, and a reload lands on the same page. The two appending modes do not change the address: a reload puts the shopper back at the top with page one. That is what every storefront does, and it is why a long catalogue wants Pagination rather than Scroll more.

The group is hidden when the layout is a slide. A carousel already pages through its feed with its arrows and dots; a second mechanism over the same list would be two things fighting, so the control is hidden rather than left sitting there doing nothing.

With Load more, the Button text field is words a shopper reads — write them in your store's language, not the editor's. The other two modes have no such field: the numbers label themselves and the scroll trigger is invisible.

Both the pager and the button carry their own styling panel, opened from that same group: alignment, the gap above the grid, cell size or button height, side padding, corner radius, background, text colour and border — plus a hover state, and for the pager the cell you are on. Every value can differ per screen size.

On the canvas, when there is not enough data for two pages, the editor says so rather than showing an empty control: "Preview — {count} items, {size} per page. The live page shows the control only from 2 pages up." In scroll mode the trigger is invisible by construction, so the canvas labels it: "Scrolling here loads more." That is about the canvas: live, the number is your whole catalogue.

The empty state

A list can come back with nothing — a filter too narrow, an empty collection, or a shopper searching for something you do not sell.

You can design that state rather than leaving white space. Turn on Previewing the empty state on the canvas to see and edit it: a sentence, an icon, a way back.

The editor also previews the loading state and the card template, so you can check all three without inventing fake data.

Storefront filters

The Storefront panel carries filter elements — checkboxes, radios and colour swatches — so shoppers can narrow a list themselves.

What a click actually does

When a shopper clicks in the Configure panel has three answers, and they differ in kind rather than in speed:

• Filter the product list — the default, and the only behaviour before August 2026. A click loads a new address, so a filtered result has its own address: a shopper can bookmark it, share it, and a search engine can read it. That is a deliberate trade against instant filtering.
• Open the category page — each row is a link to that category's own page. This is no longer a filter but a browse tree: the shopper does not narrow the list in front of them, they leave for somewhere else. Offered on the two sources that HAVE a category tree (product categories and blog categories) — elsewhere the values have no page to open. Not offered on the Select element either: it draws <option>, and an <option> cannot carry a link.
• Only fire an event (no reload) — narrows nothing and fires a wb:filter event for your own code. For when you are writing the handling yourself.

A row with no slug still appears but is not a link — it has no address, and a link back to the shop root wearing a category's name is worse than no link.

A filter that follows the page

Select filter value offers This page's sub-categories on the two category-tree sources. It reads the slug in the address and takes the children of the category the page is serving — the same mechanism as the collection grid above, so one Collection template is enough: open /collections/shirts and the sidebar lists the branches of "Shirts", open /collections/shoes and it lists the branches of "Shoes".

Off a Collection template it shows nothing, and that is where it differs from the collection grid on purpose. An empty grid still holds its place in the layout; a filter falling back to the whole catalogue would be lying — it looks exactly like the branches inside what you are currently viewing.

Two fields beside it trim the tree to fit a sidebar:

• Levels to show — 1 is root categories only. Blank shows every level.
• Most rows — blank is no limit.

Both apply to the Select element too, not only to a list of checkboxes — the same Configure panel means the same rules.

The order is levels first, then rows, and it matters: five rows over a tree already cut to one level gives you five root categories, while cutting rows first gives you the first five of a depth-first walk — usually one root and four of its children. The canvas and the published page apply the same order.

The way back: an "all" row

Once the filter is a browse tree, a shopper can walk in but not out: clicking "Dress shirts" leaves for another page, and nothing offers them all of "Shirts" again. The Add an "all" row switch builds that row — a link back to the category the page is serving, placed first.

Do not create an "All" category in the shop to do this. It would be filed with the real ones: a sibling of "Shirts" and "Shoes" in every other filter, in the collection grid, in the product form's category picker and in your own category list — a row that exists to be a link, stored as a thing products can belong to. The need is presentational, so the element draws it.

What that row says is the wording a shopper reads. Turning the switch on fills it with "All"; clear it and the row takes the name of the category the page is serving, so on /collections/shirts it reads "Shirts".

The row is not counted against Most rows, because it is not one of the values being trimmed — it is the way out. A limit of five gives you five categories and the way back, not four and the way back.

The switch appears only where it means something: the This page's sub-categories source with the Open the category page behaviour. Under in-place filtering, "all" is already what an untouched filter shows.

Blog categories browse too

Open the category page works on the Blog category source as well, and it leads to the blog's own address (/blog-categories/...), not to a product collection URL.

This page's sub-categories does not: what it follows is the page's product category, /collections/{slug}. A blog-category template has no such thing, so on that source you still pick the list by hand — which is why Select filter value does not offer it there.

A row with no slug — a product category or a blog one — still appears but is not a link. It has no address, and a link back to the listing root wearing a category's name is worse than no link.

A list can also refuse being narrowed: its own Can narrow this list group holds two switches — one for the search box, one for filters. See Storefront search.

Trying it

On the canvas you see the shape and some real data. Paging, filtering and the full repeat run on the published page — use Preview to walk all of it without publishing.

Articles

The same machinery applies to the blog: there are list elements for Articles and Blog categories. See Writing articles.

The Article list's Source field has four answers, shaped like the product list's:

• Automatic (this page) — the category the page itself is. On a Blog template (/blog-categories/{category}) the list fills with that category's posts, so one page serves every category. Anywhere else it shows every article, and the panel says so first.
• All articles — everything published. On a Blog template this source narrows to the category being viewed as well, and its label changes to "All articles in this category" to say so.
• One named category — that category's posts, even while the page is serving a different one. A "More from Life" shelf on a News page is exactly this, and it gets its own read rather than filtering the page's feed.
• The name of a relation block — a shelf you picked by hand, per article. See Relation blocks.

Source only offers blocks that hold articles; a block of products never appears here, for the mirror of the reason given there.