🔁 The WordPress Loop

What the Loop Does

Before a single line of your template runs, WordPress has already looked at the URL, run a database query, and stashed the matching posts in a global object called $wp_query. The Loop is the code that iterates over those results and displays each post. Without it, WordPress would just be a database with no way to show its contents.

💡 A useful analogy: Picture a factory conveyor belt. WordPress loads the belt with products (posts). The Loop moves the belt one item at a time; at each stop, template tags stamp on the title, attach the content, and add the byline. When the belt is empty, the Loop stops and the finished page rolls out.

The Loop cycles until have_posts() returns false.

Anatomy of the Loop

Here is the canonical Loop. Every WordPress theme contains some version of it:

<?php
if ( have_posts() ) :
    while ( have_posts() ) :
        the_post();
        ?>
        <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
            <h2>
                <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
            </h2>
            <div class="entry-content">
                <?php the_content(); ?>
            </div>
        </article>
        <?php
    endwhile;
else :
    ?>
    <p><?php esc_html_e( 'Sorry, no posts matched your criteria.', 'my-theme' ); ?></p>
    <?php
endif;
?>

Four pieces do all the work:

The alternate PHP syntax (if ( … ) : … endif;) shown above is preferred in templates because it interleaves cleanly with HTML. You'll also see the compact one-line form while ( have_posts() ) : the_post(); in production themes — it means exactly the same thing.

The Loop in Different Contexts

The beauty of the Loop is that its structure never changes, but the posts flowing through it do — WordPress prepares the right query for each context automatically. Your job is just to display what arrives.

Archive / blog index — a list of summaries

On archives and the blog index you typically show excerpts and a pagination control:

<?php
if ( have_posts() ) :
    while ( have_posts() ) :
        the_post();
        ?>
        <article>
            <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
            <p class="meta">
                <?php printf(
                    /* translators: %1$s date, %2$s author */
                    esc_html__( 'Posted on %1$s by %2$s', 'my-theme' ),
                    get_the_date(),
                    get_the_author()
                ); ?>
            </p>
            <div class="excerpt"><?php the_excerpt(); ?></div>
        </article>
        <?php
    endwhile;
    the_posts_pagination();
else :
    ?>
    <p><?php esc_html_e( 'No posts found.', 'my-theme' ); ?></p>
    <?php
endif;
?>

Single post — one full post

On a single post the query holds exactly one post, so the Loop runs once. You show the full content and often the comments:

<?php
while ( have_posts() ) :
    the_post();
    ?>
    <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
        <h1><?php the_title(); ?></h1>
        <?php if ( has_post_thumbnail() ) : ?>
            <figure class="featured-image"><?php the_post_thumbnail( 'large' ); ?></figure>
        <?php endif; ?>
        <div class="entry-content"><?php the_content(); ?></div>
        <footer><?php the_tags( 'Tags: ', ', ' ); ?></footer>
    </article>
    <?php
    if ( comments_open() || get_comments_number() ) {
        comments_template();
    }
endwhile;
?>

Even for a single post you still write the while loop. It runs once, but keeping the structure means the_post() is always called to set up the post data.

Search results — the same Loop, richer context

Search results reuse the identical pattern, adding the query term and result count:

<h1>
    <?php printf( esc_html__( 'Results for: %s', 'my-theme' ), '<span>' . esc_html( get_search_query() ) . '</span>' ); ?>
</h1>

<?php if ( have_posts() ) : ?>
    <p><?php printf( esc_html__( 'Found %d result(s).', 'my-theme' ), (int) $GLOBALS['wp_query']->found_posts ); ?></p>
    <?php
    while ( have_posts() ) :
        the_post();
        ?>
        <article>
            <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
            <div class="excerpt"><?php the_excerpt(); ?></div>
        </article>
        <?php
    endwhile;
    the_posts_pagination();
else :
    ?>
    <p><?php esc_html_e( 'No results. Try a different search.', 'my-theme' ); ?></p>
    <?php get_search_form(); ?>
<?php endif; ?>

Template & Conditional Tags

Inside the Loop you reach for two families of functions.

Template tags: display data

$title = get_the_title();
if ( str_contains( $title, 'Featured' ) ) {
    echo '<span class="badge">⭐</span>';
}
echo esc_html( strtoupper( $title ) );

Conditional tags: branch on state

Conditional tags let you vary the markup per post. A few you'll use constantly:

• has_post_thumbnail() — does this post have a featured image?
• is_sticky() — is it pinned to the top?
• has_tag() / has_category() — does it have these terms?
• 'post' === get_post_type() — is it a standard post (vs. a page or custom type)?

<?php while ( have_posts() ) : the_post(); ?>
    <article <?php post_class(); ?>>
        <h2><?php the_title(); ?></h2>

        <?php if ( has_post_thumbnail() ) : ?>
            <div class="thumb"><?php the_post_thumbnail( 'medium' ); ?></div>
        <?php endif; ?>

        <div class="entry-content"><?php the_excerpt(); ?></div>

        <?php if ( 'post' === get_post_type() ) : ?>
            <p class="cats"><?php the_category( ', ' ); ?></p>
        <?php endif; ?>
    </article>
<?php endwhile; ?>

Secondary Loops with WP_Query

The main Loop shows whatever WordPress decided to fetch for the current URL. But often you want an additional list — "featured posts," "recent posts in the sidebar," "related articles." For that you create a secondary loop with a fresh WP_Query.

💡 Back to the factory: the main conveyor belt handles the standard product line. A secondary loop is a smaller extra belt you switch on for a special batch — and switch off cleanly when you're done.

<?php
$featured = new WP_Query( array(
    'post_type'      => 'post',
    'posts_per_page' => 3,
    'meta_key'       => 'is_featured',
    'meta_value'     => 'yes',
) );

if ( $featured->have_posts() ) : ?>
    <section class="featured">
        <h2>Featured</h2>
        <?php while ( $featured->have_posts() ) : $featured->the_post(); ?>
            <article>
                <h3><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
                <?php the_excerpt(); ?>
            </article>
        <?php endwhile; ?>
    </section>
    <?php
    wp_reset_postdata(); // ← restore the main query's current post
endif;
?>

Common WP_Query parameters

Worked example: related posts by category

A classic use of a secondary loop is showing related articles under a single post:

<?php
$categories = get_the_category();
if ( $categories ) :
    $ids = wp_list_pluck( $categories, 'term_id' );

    $related = new WP_Query( array(
        'category__in'        => $ids,
        'post__not_in'        => array( get_the_ID() ), // exclude the current post
        'posts_per_page'      => 3,
        'orderby'             => 'rand',
        'ignore_sticky_posts' => true,
    ) );

    if ( $related->have_posts() ) : ?>
        <section class="related">
            <h2>Related posts</h2>
            <div class="grid">
                <?php while ( $related->have_posts() ) : $related->the_post(); ?>
                    <article>
                        <?php if ( has_post_thumbnail() ) : ?>
                            <a href="<?php the_permalink(); ?>"><?php the_post_thumbnail( 'thumbnail' ); ?></a>
                        <?php endif; ?>
                        <h3><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
                    </article>
                <?php endwhile; ?>
            </div>
        </section>
        <?php
        wp_reset_postdata();
    endif;
endif;
?>

Modifying the Main Query

Sometimes you don't want a second loop — you want to change what the main Loop fetches. For example: show 12 posts per category page, or exclude a category from the blog index. The right tool is the pre_get_posts action, placed in functions.php.

<?php
function mytheme_adjust_main_query( $query ) {
    // Only touch the main query on the front end.
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }

    if ( $query->is_category() ) {
        $query->set( 'posts_per_page', 12 );
    }

    if ( $query->is_home() ) {
        $query->set( 'category__not_in', array( 5 ) ); // hide category 5 from the blog
    }

    if ( $query->is_search() ) {
        $query->set( 'post_type', array( 'post', 'page' ) );
    }
}
add_action( 'pre_get_posts', 'mytheme_adjust_main_query' );

Pick the right query tool for the job.

Hands-on Exercise

<?php
$recent = new WP_Query( array(
    'post_type'           => 'post',
    'posts_per_page'      => 5,
    'ignore_sticky_posts' => true,
) );

if ( $recent->have_posts() ) : ?>
    <ul class="recent-posts">
        <?php while ( $recent->have_posts() ) : $recent->the_post(); ?>
            <li>
                <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
                <time><?php echo esc_html( get_the_date() ); ?></time>
            </li>
        <?php endwhile; ?>
    </ul>
    <?php wp_reset_postdata();
endif;
?>

<?php
$q = new WP_Query( array( 'posts_per_page' => 4 ) );
while ( $q->have_posts() ) : the_post();
    the_title( '<h3>', '</h3>' );
endwhile;
// main loop continues below…

<?php
$q = new WP_Query( array( 'posts_per_page' => 4 ) );
while ( $q->have_posts() ) : $q->the_post();
    the_title( '<h3>', '</h3>' );
endwhile;
wp_reset_postdata();

Best Practices & Pitfalls

function mytheme_popular_ids() {
    $ids = get_transient( 'mytheme_popular_ids' );
    if ( false === $ids ) {
        $ids = get_posts( array(
            'fields'         => 'ids',
            'posts_per_page' => 5,
            'meta_key'       => 'view_count',
            'orderby'        => 'meta_value_num',
            'order'          => 'DESC',
        ) );
        set_transient( 'mytheme_popular_ids', $ids, HOUR_IN_SECONDS );
    }
    return $ids;
}

Summary & Quiz

📚 Further Reading

• Theme Handbook — The Loop
• Reference — WP_Query
• Reference — pre_get_posts

🚀 What's Next?

You can now pull content out of the database and display it. Next you'll let users reshape the theme without code, using the Theme Customization API — colors, fonts, and layouts with a live preview.