Cyber Week30% off Lifetime with code CYBER — it will never be this cheap againUntil 28 Nov, 10:00 CET

Content & media

Loops & conditions

Repeating a subtree over a query, and shipping something only when it should be there.

Two elements are logic rather than markup. Neither emits a tag of its own: a Loop emits Astro's .map(), a Condition emits a guard. They have no box and nothing to style — put a Div inside or around one when you want a box.

Loops

A loop repeats its children once per entry.

---
import items from '../data/projects.json';
---
{items.map((item) => (
  <article builder-data-element="div" class="project-card">
    <h3 builder-data-element="heading" class="project-card__title">{item.title}</h3>
    <p builder-data-element="text">{item.year}</p>
  </article>
))}

The query is in the page's frontmatter, where anyone can read it. There is no runtime layer and no server-only mystery.

What a loop can read

SourceReads
Content typea type from Content — its live rows, from src/data/<slug>.json or the type’s database
Astro collectionwhat content.config.ts declares, read with getCollection() — bindings are {item.data.title}
Data sourceWordPress, an API, a feed, a sheet, a JSON file, a list typed once, custom code — see Content types & entries
On this pagea list where the loop stands: the gallery of the entry this design is for, the categories of the post a loop around this one repeats over, the entries a relation of either links to, or a list the page’s own code declares

A glob() collection is every file its pattern names, matched the way Astro matches it: a Markdown, MDX or Markdoc file gives its frontmatter, and a .json, .yaml or .toml file is the entry’s data whole. A file() collection reads one JSON, YAML or TOML file — a list gives an entry per item, named by its id or slug, a record an entry per key — and Fields offers what the files hold.

Anything a list can hold counts as a row. ["red", "blue"] is as good a list as a list of objects, and binds as the bare {item}. Switch a loop to other data and its bindings move with it — {item.title} becomes {item.data.title} over an Astro collection — and any binding the new data has no field for is listed under the Data select, with a button that matches what it can.

Loops nest as deep as the data does. Inside a Loop over a data source, a list in each row — a project’s phases, a phase’s items — is offered under On this page, and the inner Loop’s { } picker offers that list’s own fields, four lists deep. The source’s Fields lists them as phase_items[].text; a source last tested before 1.0 needs one more Test to show them.

Relations

A Loop over a relation repeats the entries it links to, whole — every field, url included — in the order they were dragged into in the hub. Pick it in the Data select under On this page: a relation of the entry this design is for, like entry.instructor, or of the item a loop around this one repeats, like course.instructor. The linked entries are read from their own type when the site is built, so an edit to an instructor shows on every course page at the next build. A relation that holds one repeats once or not at all, and the loop’s filter, sort and limit apply to the linked entries. Fields on the canvas places a relation as exactly this: a Loop with each linked entry’s title, a link to its page when its type has entry pages.

Settings

  • Item name — what the binding is called. item by default; name it project if that reads better.
  • How many — a limit.
  • Sort by and direction — the data’s own fields, offered by name, dates first; Manual order is the order you dragged the entries into in the hub.
  • Where — a filter on a field.
  • Linked to — over a type with a relation or a taxonomy, only the entries whose relation or taxonomy holds the entry or term you pick. On an entry page, This entry lists everything that links to the entry the page is for: an instructor’s page lists the courses that name it, with no two-way relation needed.

Pages of a list

Per page on a Loop shows that many entries and makes a page for each further batch: the page itself is page 1, and the next ones are its address with /2, /3 and on. How many still caps the whole list first, so “the latest fifty, ten a page” is both set.

  • Add page links puts previous, next and numbered links under the list, as ordinary elements you style.
  • One Loop per page can be paged: the first one on the page itself, over a content type, an Astro collection, a data source or a JSON file. A Loop in a template, in a component or inside another Loop shows every entry, and its panel says so.
  • The canvas draws page 1 as it ships.

Bindings

Inside the loop, {item.title} works in text and in attributes:

<a builder-data-element="link" href={'/projects/' + item.slug}>{item.title}</a>

A binding that names something not actually in scope is emitted as literal text rather than as code — {item.x} visibly wrong in the page beats item is not defined failing the whole build.

On the canvas

A loop previews with the real rows, not a single placeholder — through the same filter, order and limit the page ships with, so a loop matching nothing draws one line saying so. Laying out three cards is a different job from laying out one, and a builder that shows you one is hiding the job. Real data — the eye in the rail, or the switch at the head of the page’s settings — shows the bindings instead.

To let visitors search, narrow and sort the list, wrap the Loop in a Filter — see Search & filters.

Conditions

A Condition decides whether what is inside it reaches the page at all: it emits {expr && (…)} with an expression of yours, and several clauses fold left to right with and / or, every step in brackets.

A condition is ordinary Astro: anything in scope on that page can decide. To keep something off the site — notes, a guide, a scratch block — or out of your way on the canvas, you need no Condition: the eye in a layer’s ⋯ menu hides that one element on the site or on the canvas, and the tree keeps its row, dimmed.

A condition is not a display toggle. display: none is styling — it ships and is read by assistive technology. A condition removes the markup from the output.