PHP Foreach

Loop over arrays in site templates

Template Mode Only

This element is only available when editing Site Templates (tcb_template posts). It does not appear in the Elements panel when editing regular pages or posts.

Overview

The PHP Foreach element creates a loop container that iterates over an array or collection, rendering its children once for each item. This is essential for displaying repeated content like gallery images, team members, ACF repeater fields, or any array-based data.

PHP Foreach is a container element — drag other elements inside it to define what gets rendered for each iteration. Inside the loop, you can reference the current item using the variable name you specify (e.g., $item, $post, $image).

You can optionally track the array index by specifying a Key variable, which is useful for conditional styling (first/last item), zebra striping, or any logic that depends on position.

Settings

Configure the PHP Foreach element using these Inspector options:

Setting Description Default
Array The array or expression to iterate over. Can be a variable ($items), function call (get_field('gallery')), or any PHP expression that returns an array. $items
Key Optional variable name for the array key or index (e.g., $index, $key). Leave empty if you don't need to track position. (empty)
Item Variable name for the current item in each iteration (e.g., $item, $post, $member). $item

Field Examples

Common patterns for configuring foreach loops:

Use Case Array Key Item
Simple array $items (empty) $item
With index tracking $items $index $item
ACF Repeater field get_field('team_members') (empty) $member
ACF Gallery field get_field('gallery') (empty) $image
WordPress posts query get_posts(['post_type' => 'post', 'posts_per_page' => 5]) (empty) $post
Menu items wp_get_nav_menu_items('primary') $i $menu_item

Examples

Simple Foreach Loop

Basic iteration without key tracking:

<?php foreach ($items as $item) : ?>
  <div class="item">
    <!-- Children rendered for each $item -->
  </div>
<?php endforeach; ?>

Foreach with Index Tracking

Track position using a key variable for conditional styling:

<?php foreach ($items as $index => $item) : ?>
  <div class="item <?php echo $index === 0 ? 'first' : ''; ?>">
    <span class="number"><?php echo $index + 1; ?></span>
    <!-- Item content -->
  </div>
<?php endforeach; ?>

ACF Repeater Field

Loop over an Advanced Custom Fields repeater:

<?php foreach (get_field('team_members') as $member) : ?>
  <div class="team-member">
    <img src="<?php echo esc_url($member['photo']['url']); ?>" alt="<?php echo esc_attr($member['name']); ?>">
    <h3><?php echo esc_html($member['name']); ?></h3>
    <p><?php echo esc_html($member['role']); ?></p>
  </div>
<?php endforeach; ?>

Display images from an ACF gallery field:

<div class="gallery grid grid-cols-3 gap-4">
  <?php foreach (get_field('gallery') as $image) : ?>
    <img
      src="<?php echo esc_url($image['sizes']['medium']); ?>"
      alt="<?php echo esc_attr($image['alt']); ?>"
      class="rounded-lg"
    >
  <?php endforeach; ?>
</div>

WordPress Posts Query

Loop over posts from a custom query:

<?php
$recent_posts = get_posts([
  'post_type' => 'post',
  'posts_per_page' => 5,
  'orderby' => 'date',
  'order' => 'DESC'
]);
?>
<?php foreach ($recent_posts as $post) : setup_postdata($post); ?>
  <article>
    <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
    <p><?php the_excerpt(); ?></p>
  </article>
<?php endforeach; wp_reset_postdata(); ?>
Quick Tip

When looping over posts from get_posts(), use setup_postdata($post) inside the loop to make template tags like the_title() and the_permalink() work. Call wp_reset_postdata() after the loop to restore the global $post.

Foreach vs While

Use PHP Foreach for iterating over arrays (ACF fields, get_posts() results, custom arrays). Use PHP While for the main WordPress loop (have_posts()) or custom WP_Query loops.

Next Steps