Understanding The Loop: WordPress’s Way of Showing Posts

This article introduces one of the most important topics in WordPress development: the WordPress loop, or more commonly simply “the loop.” If you’re interested in under more of the key concepts of developing WordPress themes, check out our free course on getting started with WordPress themes.

This content is great, because it’s not just one of our normal articles: It’s a sample chapter from our “learn WordPress development” guide Up and Running, now in its revised and expanded 3rd Edition.

If you like this chapter, check out Up and Running. There’s about 40 more chapters where this one came from. It’s the best guide to WordPress development out there.

The Best Way to Learn WordPress Development

Get Up and Running Today!

Up and Running is our complete "learn WordPress development" course. Now in its updated and expanded Third Edition, it's helped hundreds of happy buyers learn WordPress development the fast, smart, and thorough way.

Here's what one of them had to say:

"I think anyone interested in learning WordPress development NEEDS this course. Watching the videos was like a bunch of lights being turned on." -Jason, WordPress developer

Get Up and Running Now

The Loop is perhaps the key concept of WordPress theme development, so you’ll definitely want to wrap your head around it. Fortunately, it’s not that complicated! Our goal here is to make the concept clear first, and then to move on and show you how the code works.

Once we know which template file we’re working with, it’s time to get into the guts of the file itself, and that’s where we’ll find The Loop.

The WordPress Loop is how WordPress processes any bundle of fetched posts.

Inside The Loop, you specify how you want each post in the fetched bundle to be laid out. WordPress will “loop through” the bundle, and reuse the specified format for every post in the bundle—which is why it’s called The Loop.

So The Loop is most obvious on, for example, your blog index page, where WordPress cycles through lots of blog posts, reusing the format we’ve specified for each one.

However, if there’s only one post on the webpage—when someone requests, say, a single blog post, or the site’s “About” page—WordPress will still use the core concept of The Loop to display the (single) post on the webpage.

The Loop is the engine of any template file, and it’s highly customizable; it varies file-by-file. Changing Loop contents is a primary way to make your template files behave differently.

For example, you might want to make your blog index page (controlled by your theme’s home.php) show only one-paragraph excerpts of your blog posts, instead of the whole content. To do this, you’ll use the the_excerpt() template tag inside home.php‘s Loop. (We cover template tags later, in The Magic of the_() and get_the_() Post Template Tags—they’re cool!)

At the same time, you still want the webpages for your individual blog posts (controlled by single.php) to display the entire article contents, not just an excerpt. So inside the single.php Loop, you’ll use the the_content() template tag, instead of the_excerpt().

Being able to dictate these differences is a lot of what WordPress theme development is all about.

Below you’ll see the single.php file for WordPress’s popular Twenty Fifteen theme. The Loop is on lines 15 to 43. We won’t scare you yet with what’s inside The Loop itself (so lines 18 to 39 are hidden)—but notice that single.php isn’t much but The Loop! In other words, The Loop is doing almost all the work that makes this template file display its contents.

So that’s a Loop in the wild. Now let’s leave Twenty Fifteen alone and talk about the general anatomy of a Loop in any theme.

<?php
/* Environment: We're inside a theme template file in the WordPress template hierarchy */

if ( have_posts() ) {
    while ( have_posts() ) {
        the_post(); 

        // (Loop contents will go here)

    } // end while
} // end if

Or…

<?php
/* Environment: We're inside a theme template file in the WordPress template hierarchy */

if ( have_posts() ) :
    while ( have_posts() ) :
        the_post(); 

        // (Loop contents will go here)

    endwhile;
endif;

Don’t get too hung up on there being two ways to write The Loop—they’re just two ways of “punctuating” PHP, and they mean the same thing. We prefer the second way of writing it, so we’ll be sticking with that one through the rest of the chapter.

In this section, we’ll offer a line-by-line explanation of the second Loop example above (the one with the endwhile in it).

The first thing to notice is that The Loop really is a loop, in the programming sense. In other words, it iterates (loops) over a set of WordPress posts—and doesn’t stop until it runs out of posts. Here’s how that works, line-by-line:

If the answer we get back from have_posts() is true, then what’s inside the if-statement—which is The Loop itself—will operate. If not, then our PHP engine skips right over The Loop, because there’s nothing to loop through!

In English, this line says “While we still have posts to process:” In other words, this loop will execute the code inside it once per post, while there are still posts to act on. When there are no more posts, The Loop will stop, and the page will move on to the next thing in this PHP template.

the_post() is what does the “queueing up”—it basically sets up the next fetched post object to be worked on by the WordPress processes available to us within The Loop. The Loop requires this function, but we don’t have to know too much more about it than this.

<?php 
/* Environment: We're inside a theme template file in the WordPress template hierarchy */

if ( have_posts() ) :
    while ( have_posts() ) :
        the_post(); ?>

        <article class="full-article">
            <h2><?php the_title(); ?></h2>
            <?php the_excerpt(); ?>
        </article>

    <?php endwhile;
endif;

So taking some Posts from the blog of our site Press Up as examples, the Loop above outputs:

<article class="full-article">
    <h2>What Your Minimum Viable Product Should Be Measuring</h2>
    <p>In our last article we introduced you to the idea of the Minimum Viable Product (MVP), and covered some of the internal challenges that often arise when you prepare to share a beta version of your idea. An MVP isn't just a quick, cheap version of your product that you're releasing because it's easy. On […]</p>
</article>


<article class="full-article">
    <h2>Starting Small: Creating a Minimum Viable Product</h2>
    <p>A common mistake entrepreneurs make is to start with a very specific idea and grind as hard as possible to make it work. This might work out great—but as many entrepreneurs learn, it's far too easy to rush through, or entirely overlook, the process of refining our initial ideas into something people truly want. Not […]</p>
</article>


<article class="full-article">
    <h2>How to Plan a Successful Web Project</h2>
    <p>It's too easy to plan out a web project in terms of technologies rather than solutions. Too many web projects don't meet their goals. The project could be the wrong solution for the right goal, the right solution for the wrong goal—or, perhaps worst of all, a shiny solution for no goal. The problem is […]</p>
</article>

// (And so on for many more articles)

1. Notice how we move in between plain HTML and PHP. Remember, anything not inside <?php ?> is pure HTML: in our case, that’s the <h2> and <article> tags. Those get printed out directly to the webpage every time The Loop iterates over a new post.
2. The real meat here—and where we’re getting deep into the magic of WordPress—is the two PHP template tags we’re using: the_title(), which, when used inside The Loop, prints out the current post’s title; and the_excerpt(), which prints out the beginning of the post’s content. We cover template tags in detail in The Magic of the_() and get_the_() Post Template Tags.

If you made a theme whose only template hierarchy file was index.php, and pasted the above Loop into that index.php file, it would work. Your site’s homepage would display all the titles and excerpts of your most recent Posts, your site’s “About” page would display the title and excerpt of that Page’s copy, and so on.

Again, you’ll learn more about programming the innards of The Loop with template tags like the_content() in The Magic of the_() and get_the_() Post Template Tags. For now, though, you’re Loop-literate, and that’s a great thing! This is one of the most important parts of WordPress theme development.