Pagination

Pagination splits a loop's results across pages instead of rendering all of them at once.
It's available on the Post Loop and the
Term Loop; the Repeater Field
has no pagination.

Choosing a mode

Content → Pagination holds a single dropdown with six modes, plus whatever extra
fields that mode needs:

• None — render one page of results and stop. This is the default.
• Numbers — numbered page links.
• Previous / Next — just the two direction links.
• Numbers + Previous / Next — both.
• Load More Button — a button that appends the next page in place.
• Infinite Scroll — the next page loads automatically as the visitor reaches the end.

The extra fields appear only for the modes that use them:

Field	Appears for
Previous Text, Next Text	Previous / Next · Numbers + Previous / Next
Show All Page Numbers	Numbers · Numbers + Previous / Next
Load More Text	Load More Button

Infinite Scroll has no extra fields — there is no button to label.

How the page size is set

Pagination does not decide how many items a page holds; the loop's own query does.

• On a Post Loop, that's Posts per page in the
  Query Builder — or eight, if you never
  set a query.
• On a Term Loop, it's the Limit field. With pagination on and Limit empty,
  Breakdance uses 10 terms per page.

So "show 2 per page with numbered links" is two settings in two places: the count in the
query, the links in Pagination.

Styling

Design → Pagination styles the controls: Alignment, Space Above, Space
Between, Typography and an Active Color for the current page. Turn on Display
As Buttons to get a full button treatment — size, border, background, radius, and a
separate Active state with its own border, background and text colours.

The Load More Button has its own design section, including a loading icon with size
and colour, and a Show Loading Icon In Builder toggle so you can style the loading
state without waiting for a real request.

Two things that will catch you out

Pagination and a custom query don't mix inside an archive template. Both want to own
the page number, and Breakdance can't reconcile them — the builder shows the error
"Pagination with Custom Queries in Archives isn't supported". Inside an archive template,
either leave the query untouched so the loop inherits the archive's own results and
paginate that, or use a custom query and drop pagination.

The Filter Bar replaces pagination. On a Post Loop, enabling
Filter Bar hides the Pagination section entirely.
The filter works by showing and hiding already-rendered items, so a paginated loop would
only ever filter the current page. Use one or the other.

Note: the empty state is deliberately not
rendered by Load More or Infinite Scroll requests. Those fetch additional items for a
loop that already produced results, so an "if there are no results" design would be
wrong there.

Query Sources and Page Numbers

• Custom > Post Types supports pagination; Related and ACF Relationship discard the page number.
• Text queries do not merge the loop's pagination arguments.
• Array queries can inherit pagination; fixed paged or offset values can override it.
• Filter Bar filters loaded items and hides normal pagination.
• Repeater Field and Flexible Content have no native pagination.

Requesting all posts with -1 leaves nothing to paginate. Total posts caps the overall Post Types collection. Slider arrows navigate existing slides, not additional query pages.

If a capped final page repeats earlier items, check Total posts as well as fixed paged or offset arguments. Random ordering can repeat or omit items between requests. Slider arrows move through already-loaded slides; they do not fetch query pages.