Listing

A Listing fills a container with items pulled from a query, so the set stays up to date as content is added or changes.

What it is

A Listing is a query that fills a container with items, kept up to date automatically as content is added or changes — a news feed (newest first), the contents of a section, or everything on a topic. A Listing always lives inside a container (a Cards grid, Link list or Tags block), and the container decides how each result is shown: a Cards grid as cards, a Link list or Tags block as links. A Listing is never a standalone block; for a list the reader can filter or search themselves, use a Search block instead.

NSW Design System

How to
Example

How to add it

Add a container first — a Cards grid, Link list or Tags block — then add a Listing inside it and set its criteria. A Listing can also be dragged from one container to another, and re-renders in the new container's item type.

Drag a listing between containers

A Listing is a structural child: drag it from one container into another and it re-renders as that container's item type. The Example tab shows one Listing rendered as a link list and as tags.

Drag a listing from a link list into a tags block

Configure it

Criteria

Criteria are the rules that pick which items show — by part of the site, tag, content type, publication or modification date, and so on. Leaving the criteria empty shows the contents of the current page; to show the current page's contents in a chosen order, use the path criterion with a relative path of “.” and pick a sort.

Pick the criteria — by part of the site, tag or type — and the list keeps itself up to date.

Item type

How each result renders is the container's item type — links in a Link list or Tags block, cards in a Cards grid, or list items. In a Cards grid the grid syncs the type across every item; each item pulls its title, date, tag and image from the linked page. The Example tab shows a query rendered as cards.

The container decides how results render — the same query, switched from cards to content blocks and back.

Pagination

The container owns paging: limit how many items show at once, or show a page at a time and let the reader click to see more.

Tips

Keep criteria as tight as the need — a whole-site query is rarely what a reader wants. Sort so the most useful item is first (newest, or alphabetical).

Item content comes from the linked pages, not the listing — to change a title or preview image, edit the source page.