The WordPress Loop Explained: What It is and How It Works

The loop is a central part of WordPress. Without it, you would not see content on any WordPress website. It’s responsible for making sure that articles appears on the blog page and in archives as well as static content on single pages.

If you are a theme designer, you will not get around learning how to use it. However, as a casual WordPress user, you might not even be aware that it exists.

In order to alleviate that, in this post, we will explain the WordPress loop in detail. We will go over what it is and how it works, and where to find it in WordPress. You will also learn how to create your own and see some examples of the WordPress loop to solidify your understanding of it.

What is the WordPress Loop (And Where Do You Find It)?

If you were to briefly explain what the WordPress loop is, it’s simply the markup that fetches and outputs content on pages in a WordPress website. Whether that is a static page, post, blog page, or archive – anywhere that WordPress pulls content from the database and displays it on a page, the loop is involved.

However, why is it called loop in the first place?

Because it will run repeatedly. Plus, as you will see below, it literally consists of a PHP loop.

How often does the WordPress loop run?

Until there is nothing left to display. Even on static pages it loops through the available content. However, in this case, it stops after one pass.

What Does the WordPress Loop Look Like?

To make it clearer what we are talking about, let’s look at an example and go over it step by step. Here’s an example of what a simple WordPress loop looks like:

if ( have_posts() ) : 	while ( have_posts() ) : 		the_post(); 	 	// Display content here 	 	endwhile; endif;

If you already know PHP or are a WordPress developer, you should not have any problem understanding it. However, for everyone else, let’s go over the pieces one by one.

if ( have_posts() ) : — This is an if statement that’s using the have_posts() function. If statements are common in programming, they simply say “if the following condition applies, continue”. In this case, the condition is have_posts(), which is simply a check for whether any posts exist that could be displayed.
while ( have_posts() ) : — This line is a while-loop and marks the beginning of the WordPress loop. It will execute code it contains as long as its condition is true. Again, the condition is whether WordPress has any posts in store. How often it will return true is determined by the number of posts set in the WordPress settings in the admin interface.
the_post(); — This is the code that the loop executes. It’s a WordPress function that calls all the available data for the next post and saves it to get it ready for display. For that, we have a lot of template tags that we will talk about below.
// Display content here — Here’s where we place the markup that determines which part of the content to display and in which manner. It’s usually a mix of PHP and HTML. We are not showing it here because it’s more complex and we will go over it later.
endwhile; — The piece of code that closes the while-loop after it has done what we need it to do.
endif; — Same as above but for the if statement.

So, basically the structure is as follows: check if posts exist, then pull the necessary data from the database and display it in a pre-determined way, repeat this as long as there are valid posts to display.

Alternative Syntax

One quick thing, you will also sometimes see the loop written like this:

if ( have_posts() ) { 	while ( have_posts() ) { 		the_post();  		 		// Display content here 		 	} // end while } // end if

This is exactly the same as the example above, just in an alternative PHP syntax. Which one you use is really up to you. For consistency’s sake, we will continue with the first variation.

Where to Find the WordPress Loop?

The fact that the loop is always at work whenever content appears on a page already answers where to find the WordPress loop. The answers is in every template file of your theme that displays content.

Alternatively, depending on your theme architecture, it might also be in a template part. These are template files that contain frequently used code pieces (such as the loop). They can be pulled into other files instead of reusing the same code snippet each time.

wordpress loop in template parts theme architecture example

For example, if you open the page.php file of the Twenty Twenty-One theme, you can see that, here, the loop is split into parts. While it starts inside the file itself, the section that determines how to output the data resides in a template part called content-page.php.

/* Start the Loop */ while ( have_posts() ) : 	the_post(); 	get_template_part( 'template-parts/content/content-page' );  	// If comments are open or there is at least one comment, load up the comment template. 	if ( comments_open() || get_comments_number() ) { 		comments_template(); 	} endwhile; // End of the loop.

The WordPress template hierarchy determines which file the system uses to display what kind of page and each file needs to contain either a loop or a reference to where you can find it.

It also means that the loop can look different in individual files, meaning on different pages. For example, in an archive you might only want to display post excerpts, while on the main blog page, you might want to show entire posts (up to the “read more” link). For that, you need different kinds of markup, which is why the loop would not looks the same inside home.php and archive.php.

How to Create a Loop

In order to create a loop, you can basically start with the simple code we dissected above. That’s really the standard loop. Here it is again:

 if ( have_posts() ) : 	while ( have_posts() ) : 		the_post(); 	 	// Display content here 	 	endwhile; endif;

The tricky part is what we left out: the part that determines the display of the content. For that, as mentioned, you usually use a mix of HTML and PHP. For example, here is how you would tell WordPress to spit out the post wrapped in an

tag with a custom class and id, the title as an h1 heading, plus the featured image and content.

 	 	 id="post-">

One thing that stands out above is that there are lots of tags written with underscores. These are WordPress template tags, which offer shortcuts for calling common parts of content. Here, we use the_title() for displaying the post title, the_post_thumbnail() for the featured image, and the_content() for the main content. There are a lot more, such as the_excerpt() or the_category(). You can find a list of options here.

Another thing that is important for the WordPress loop are conditional tags. You see them used a lot in loop-related markup to display something only under certain conditions. For example, it’s very common to wrap the_post_thumbnail() into a conditional statement to keep WordPress from trying to put it out on the page when no featured image exists.

We have more examples below. To learn more about conditional tags, check the WordPress Codex.

Examples of the WordPress Loop

As the final part of this tutorial, we will go over some examples for how to use the WordPress loop.

The Twenty Twenty-One Theme

When looking at the Twenty Twenty-One theme, the first thing that stands out is its heavy use of template parts. All the standard template files like page.php, single.php, and even index.php start the loop inside the file but then use get_template_part to offload content display to other files. In this case, that’s content-page.php, content-single.php, and content.php respectively. Here’s a shortened version of single.php as an example:


This is also also visible in other files. For example, the header and footer also have their own template parts. You can see references to those inside the loop in other places. For instance, if you look at content-single.php, you can see a call to the author-bio.php template part at the end.
>  	 		', '' ); ?> 		 	
  	 		 '', 				'after'    => '
', 				/* translators: %: Page number. */ 				'pagelink' => esc_html__( 'Page %', 'twentytwentyone' ), 			) 		); 		?> 	
  	 		 	
  	 		 	  

Aside from that, it’s relatively standard fair:

Open an 

 HTML element with a custom id and class
Create the article header element that outputs the title wrapped in an h1 heading and displays the featured image with a function that’s custom to Twenty Twenty-One
Follow that up with an entry-content element that contains the the_content() template tag to output single-post content
Include markup for pagination and the entry footer with another Twenty Twenty-One function for displaying post meta information
Finally, there is the aforementioned call to the author bio in its own template part

The Twenty Ten WordPress Default Theme
If you go back to the first ever WordPress default theme, Twenty Ten, and use the subversion repository to look at files from version 1.0, you can see how handling the loop and template files has evolved over time. Back then, many of the template files contained their own complete WordPress loops instead of outsourcing them to reusable template parts. You can see this clearly in the theme’s page.php.
  		 			    				> 					 						
 						 						
 									  					 						 						 '' . __( 'Pages:', 'twentyten' ), 'after' => '
' ) ); ?> 						', '' ); ?> 					
 				
  				    			
 		
   
The same is also visible in onecolumn-page.php, which is a file that controls a custom page template the theme offers. What’s also noteworthy is that it’s using the older call to the loop which was written in one line back then.

In modern themes, you most commonly see it spread out over several lines as seen earlier to increase code readability.
The Twenty Ten theme also has a standalone loop.php file that is way too long to include here without exceeding my word limit. It is divided into three parts that control the display of several types of posts (image gallery, posts from the Asides category, all other posts). Each of these are further broken down by if and else statements to account for different cases like archive and search pages.
  	 	 	// Lots of code here   				 	// Lots of code here as well    		 		 			// Even more code  		  	 		 		// Still more code 		 	 			 		// A bit more markup 	 	  		// And a bit more code  	  
The whole thing contains a pretty convoluted logic which is why it comes out rather long and complicated. I am glad we have other ways of handling these today and I recommend you have a look at it to see a WordPress loop example you don’t want to emulate.
By the way, if you think I am being too harsh on the developers from back then, rest assured, they agree with my assessment. Just look at the developer comment where loop.php closes the loop.

The WordPress Query Loop Block
You might not be aware of it because is a relatively new Gutenberg feature but the block editor (and by extension, full-site editing) now also has a block that contains a WordPress loop. It’s called the Query Loop Block and you can add it to your site like any other block. The easiest way is to add a forward slash and type out its name like /queryloop. Hit enter and it will appear on the page.

The block allows to create a PHP loop without having to write code. It will automatically display the latest posts on your site. Besides that, it has several customization options. First of all, the block comes with a number of preset layouts. You can either cycle through them via the arrows or click on the Grid option to see them all at once.

Pick whichever you like or click on Choose if you have arrived at your favorite option to finalize the choice. It’s important to note that the layouts consist of block patterns, so prearranged groups of single blocks. This also means you can arrange them differently as needed, they are still normal blocks. Use the arrows or click and hold the Drag option to move them around where you want.
In addition, each block (and often each block group) also comes with their usual options in the main editor screen and in the sidebar. Here, you can change their colors, font sizes, formats, and more.

Once satisfied, if you publish or preview the page, you will see your custom WordPress query loop appear on it. So, even if you are not a WordPress developer and don’t understand PHP, you can still take advantage of what the loop has to offer.
The WordPress Loop Explained in Nutshell
The loop is something that any WordPress professional has to be familiar with. However, even if you are a more casual user, it’s still not a bad idea to understand how it works. It might make it easier to troubleshoot problems or create custom page templates if you so wish.
In this post, we have gone over what the loop is, where it resides, and broken it down in detail. We have also had a look at how you can create your own loop and examples from default themes and the new query block. By now, you know all you need in order to create and customize the WordPress loop.
What’s your favorite use of the WordPress loop? Please share your thoughts in the comments below!
Images: Jonny Gios/Unsplash, Tine Ivanič/Unsplash






Author
Nick Schäferhoff

Nick Schäferhoff is an entrepreneur, online marketer, and professional blogger from Germany. He found WordPress when he needed a website for his first business and instantly fell in love. When not building websites, creating content or helping his clients improve their online business, he can most often be found at the gym, the dojo or traveling the world with his wife. If you want to get in touch with him, you can do so via Twitter or through his website.
More articles by Nick Schäferhoff