Loop

The Loop tag gets items of site content by type, and repeats a template for each item.

Example

<Loop type=post count=3>
  <Field title />
</Loop>

In this example, the loop type is post.

The count attribute limits the number of items.

For each item in the loop, the template will display the title field of the item.

Concepts

  • Loop type is the name of the type of content items to get.

    It is usually in singular form, for example: post, page, or user. The name must be lowercase letters, and can contain numbers, - (dash) or _ (underscore).

  • Loop query means how to search, filter, and sort items.

    This is achieved by passing attributes, also called query parameters, to the Loop tag.

  • A field is a detail of the current item in the loop, such as title, author, and published date.

    The Field tag is used for this purpose.

  • There are ways to show or skip content based on conditions.

    This is done with the If tag, usually by checking an item's field values.

Loop types

The type attribute defines the loop type, usually corresponding to a post type.

Each loop type has a set of available query parameters and fields.

Core content

Field loop

These loop through a field value that is a list or map (associative array).

  • Field - field
  • User field - user_field

Abstract data

These loop through data created by List and Map tags, or passed directly as attribute value.

  • List - list
  • Map - map - Loop of a single item, which is a map
  • Map keys - map_keys - Loop of all keys in a map

Integrations

There are loop types that integrate with content from other plugins.

Limit item count

Use the count attribute to limit the total number of items.

Filter by field

Use the field attribute to filter items by field.

  • field - Field name by which to filter
  • field_value - Field value
  • field_compare - Comparison operator: equal, not, more_than, less_than, ..
  • field_type - Field type: string (default), number, date

Sort by field

Use the sort_field attribute to sort items by field.

  • sort_field - Field by which to sort
  • sort_order - Sort order - asc for ascending (default), or desc for descending
  • sort_type - Sort type - string (default), number, date

Variables

Use the Get tag and variable type loop to access variables related to loop.

<Get loop=count />
  • count - Current loop count, an index starting from 1
  • total - Total number of items in current loop
  • previous_total - Total number of items in previous loop, after it's closed

Field loop variables

For fields that are loop instances, like a list or ACF repeater, use the field attribute (or ACF field type) to specify the field name.

For example, to get the number of total items in a repeater field:

<Get loop=total acf_repeater=field_name />

Pagination

This is a feature for AJAX pagination of loops.

With the Loop tag, use the paged attribute to define the number of items per page.

Currently, the loop types list and map are not supported.

Buttons

After the loop, use the PaginateButtons tag to display pagination.

<PaginateButtons />

Fields

Optionally, use the PaginateFields tag to display current pagination state.

<PaginateFields>
  Page <Field current_page /> of <Field total_pages />
</PaginateFields>

Available fields are:

  • current_page - Current page
  • total_pages - Total number of pages

The current page will be updated as the user navigates pages.

Example

Here's a full example of loop pagination.

<ul>
  <Loop type=post paged=2>
    <li>
      <a href="{Field url}"><Field title /></a>
    </li>
  </Loop>
</ul>

<PaginateButtons />

<PaginateFields>
  Page <Field current_page /> of <Field total_pages />
</PaginateFields>

Next: Field