PHP While

Loop with condition for WordPress queries

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 While element creates a loop that continues while a condition is true. This is the standard pattern for WordPress post loops, where you iterate through query results using have_posts() and the_post().

PHP While is a container element — drag elements inside it to define what gets rendered for each iteration. The loop automatically advances using the Setup Code you provide, typically calling the_post() to move to the next post.

The most common use case is the main WordPress loop:

  • Condition: have_posts() — continues while there are posts
  • Setup Code: the_post(); — advances to the next post

Settings

Configure the PHP While element using these Inspector options:

Setting Description Default
Condition The PHP expression that must evaluate to true for the loop to continue. When it returns false, the loop ends. have_posts()
Setup Code PHP code to execute at the start of each iteration. This typically advances the loop state (e.g., moves to the next post). the_post();

Field Examples

Common patterns for configuring while loops:

Use Case Condition Setup Code
Main WordPress loop have_posts() the_post();
Custom WP_Query $query->have_posts() $query->the_post();
Counter loop $i < 10 $i++;
Array iteration $item = array_shift($items) (empty)

Examples

Main WordPress Loop

The standard WordPress post loop using the global query:

<?php while (have_posts()) : the_post(); ?>
  <article class="post">
    <h2><?php the_title(); ?></h2>
    <div class="content">
      <?php the_content(); ?>
    </div>
  </article>
<?php endwhile; ?>

Custom WP_Query Loop

Loop through a custom query result:

<?php
$featured_query = new WP_Query([
  'post_type' => 'post',
  'posts_per_page' => 3,
  'meta_key' => 'featured',
  'meta_value' => '1'
]);
?>
<?php while ($featured_query->have_posts()) : $featured_query->the_post(); ?>
  <div class="featured-post">
    <?php the_post_thumbnail('medium'); ?>
    <h3><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
  </div>
<?php endwhile; wp_reset_postdata(); ?>

Complete Loop with If/Else

Best practice: wrap while loops in an if statement to handle empty results:

<?php if (have_posts()) : ?>
  <?php while (have_posts()) : the_post(); ?>
    <?php if (has_post_thumbnail()) : ?>
      <?php the_post_thumbnail('large'); ?>
    <?php endif; ?>
    <h2><?php the_title(); ?></h2>
    <p><?php the_excerpt(); ?></p>
  <?php endwhile; ?>
<?php else : ?>
  <p>No posts found.</p>
<?php endif; ?>

Counter-Based Loop

Use a counter for fixed iterations:

<?php $i = 0; ?>
<?php while ($i < 5) : $i++; ?>
  <div class="placeholder-item">
    Item <?php echo $i; ?>
  </div>
<?php endwhile; ?>
Always Use If Wrapper

Always wrap your PHP While loop inside a PHP If element with have_posts() as the condition. This lets you use PHP Else to display a "no results" message when the query returns empty.

Reset Post Data

After custom WP_Query loops, always call wp_reset_postdata() to restore the global $post variable. Use a PHP Code element with wp_reset_postdata(); after your while loop.

Next Steps