Post Loops

The Post Loop Builder repeats a Component once per post. It's the element behind blog
indexes, related-post rows, portfolio grids, team listings — anything driven by a post
type.

It's also the most capable of the three loop elements: it is the
only one with a visual query builder, and the only one with a filter bar.

Building the loop

1. Add Post Loop Builder from Add → Dynamic.
2. In Content → Repeated Block, choose the Component to repeat, and optionally
   the Tag each item is wrapped in. This works the same on every loop element —
   see Loops.
3. Set the query, the layout, and (optionally) pagination.

The Advanced popout inside Repeated Block holds
alternates and static items and the
empty state.

Choosing what the loop shows

Content → Query decides which posts the loop renders. It offers three modes:

• Custom opens the visual Query Builder — the normal choice.
• Text takes a query string, for example post_type=post&posts_per_page=4.
• Array takes PHP that returns an array of WP_Query arguments.

The Query Builder

• Source — Post Types, Related (items related to the current one), or ACF
  Relationship when ACF is active.
• Include — which post types to pull from.
• Amount — Posts per page, Total posts, and Offset.
• Conditions — conditions drawn from the same catalog as element display and template
  targeting, narrowed to the ones that can filter a query. See
  Conditions Reference.
• Meta Query — filter by custom field values, with nested groups for complex logic.
• Order — Order By (Date, Last modified date, Title, Comments count, Menu order,
  Random — plus ACF and Meta Box when those plugins are active, each revealing a Field
  chooser) and Order (Descending or Ascending). Alongside it: a Date filter with
  Before Date / After Date, and toggles for Ignore current post, Ignore
  sticky posts, and Same author only.

Click Apply Query to commit.

Defaults, and archives

Leave the query untouched and the loop falls back to eight posts per page.

Inside an archive template, an untouched loop is special: it renders that archive's own
results rather than a query of its own. That is what lets one archive template serve
every category — the loop inherits whatever WordPress already resolved for the request.
Give the loop a custom query and you override that inheritance.

Caution: pagination does not work with a custom query inside an archive template.
The two mechanisms both try to own the page number and Oxygen can't reconcile them, so
the builder shows the error "Pagination with Custom Queries in Archives isn't
supported". Either inherit the archive query and paginate, or use a custom query
without pagination.

Layout

Loop layout is native, in Design → List:

• Layout — List, Grid, Slider, Accordion, Tabs, or Masonry.
• Items Per Row (grid and masonry) — responsive, so you can drop from three columns
  to one across breakpoints.
• One Item At (slider) and Space Between Items.
• Width constrains the list itself.

The sections below it style the items: Post (each item's background, borders,
padding), Container, Pagination, and Spacing.

Pagination

Content → Pagination offers numbered links, previous/next, a Load More button, or
infinite scroll. It's shared with the Term Loop and documented in
Pagination.

Filter Bar

Content → Filter Bar adds front-end filter buttons built from a taxonomy. This is
the one loop feature that exists only on the Post Loop.

• Enable turns it on.
• Type picks the taxonomy the buttons are built from.
• All Filter adds a show-everything button, with a custom All Label.
• Sort By orders the buttons: Name A–Z, Name Z–A, Term Order, or Count.
• Hide Uncategorized drops that term from the list.

Filtering happens in the browser — the loop renders every matching post and the filter
shows and hides them, so it is instant but not a substitute for a query on a large
archive.

Enabling the Filter Bar hides the Pagination section: a loop uses one or the other, not
both.