Explainers · Explainer
What Is the WordPress Loop? Explained

Short answer
The WordPress loop is PHP code in a theme that goes through the posts fetched for the current page and displays each one. It uses have_posts and the_post to step through posts, and template tags like the_title and the_content to print them.
Key takeaways
- The loop displays posts, while the query decides which posts appear.
- have_posts and the_post drive every loop.
- Template tags such as the_title work only inside the loop.
- Custom loops use new WP_Query and must end with wp_reset_postdata.
- Block themes use the Query Loop block instead of PHP loops.
What is the WordPress loop?
The WordPress loop is the PHP code in a theme that goes through the posts WordPress has fetched for a page and displays each one, using functions such as the_title and the_content.
Every time someone opens a page on a WordPress site, WordPress first works out which posts belong on it.
A blog page needs the latest posts. A single post page needs one post. A category page needs posts from that category.
The loop is the part of the theme that takes that list and prints it. It runs once for each post, then stops.
The WordPress Theme Handbook page on the Loop calls it the default way WordPress outputs posts. Almost every classic theme uses it.
What does the loop look like in code?
A basic loop checks whether there are posts with have_posts, then repeats a block of code for each one after calling the_post to set it up.
Here's the simplest version:
<?php if ( have_posts() ) : ?>
<?php while ( have_posts() ) : the_post(); ?>
<h2><?php the_title(); ?></h2>
<?php the_content(); ?>
<?php endwhile; ?>
<?php else : ?>
<p>No posts found.</p>
<?php endif; ?>
Read it line by line:
- have_posts asks whether there are any posts left to show.
- while keeps repeating as long as the answer is yes.
- the_post moves to the next post and makes its data available.
- the_title and the_content print that post's title and body.
- else handles the case where nothing matched.
The loop is just a normal PHP while loop. If you know a little PHP, the PHP manual's while page explains the structure.
How does the loop know which posts to show?
The loop doesn't choose posts itself; WordPress runs the main query from the URL before the theme loads, and the loop simply walks through that query's results.
When a visitor opens a URL, WordPress reads it and builds a query. A category URL creates a query for that category's posts. A search URL creates a query for posts matching the search words.
That query is stored in a global object of the WP_Query class. The functions have_posts and the_post work on that object behind the scenes.
If you want to read the code itself, the loop functions live in the wp-includes folder of the WordPress source on GitHub. Look at query.php and class-wp-query.php.
So if you want to change which posts show on a page, you usually change the query, not the loop. The pre_get_posts hook is the standard way to adjust the main query before it runs.
Our guide on how to use WP_Query explains the query side in more depth.
What are template tags in the loop?
Template tags are WordPress functions that print or return information about the current post inside the loop, such as its title, date, author, link and featured image.
Common ones include:
| Template tag | What it outputs |
|---|---|
| the_title | The post title |
| the_content | The full post content |
| the_excerpt | A short summary |
| the_permalink | The post's URL |
| the_post_thumbnail | The featured image |
| the_time or the_date | The publish date |
| the_author | The author's display name |
| the_category | Links to the post's categories |
Functions starting with the_ usually print directly. Their get_the_ versions return the value so you can use it in your own code.
Most of these only work inside the loop, because they depend on the current post the loop has set up. Outside it, they may show the wrong post or nothing.
Where is the loop used in a theme?
The loop appears in almost every classic theme template file, including index.php, single.php, page.php, archive.php and search.php.
Each template uses the same basic loop but shows different details:
- index.php shows a list of posts, often with excerpts
- single.php shows one full post
- page.php shows one page
- archive.php shows posts for a category, tag, author or date
- search.php shows search results
WordPress picks the template using the template hierarchy. Our guide on what a WordPress template is explains how that choice works.
Even single post pages use a loop. It just runs once, for one post.
What is a custom loop?
A custom loop is a second loop that runs its own query with new WP_Query, so you can show extra posts, such as related articles or a featured list, without changing the page's main query.
Here's a short example that shows three recent posts from one category:
<?php
$recent = new WP_Query( array(
'category_name' => 'news',
'posts_per_page' => 3,
) );
if ( $recent->have_posts() ) :
while ( $recent->have_posts() ) : $recent->the_post();
the_title( '<h3>', '</h3>' );
endwhile;
wp_reset_postdata();
endif;
?>
The key detail is wp_reset_postdata at the end. It puts the global post back to the main query's current post. Without it, template tags later on the page can show the wrong post.
The WP_Query class reference lists every argument you can pass.
Avoid query_posts for custom loops. It replaces the main query and causes pagination and performance problems. WordPress itself recommends against it.
How is the loop different from the Query Loop block?
The loop is PHP code inside classic theme files, while the Query Loop block is a block you place in the editor or a block theme template to do the same job visually.
Both end up running a WP_Query behind the scenes. The difference is how you build them:
- Classic loop: written in PHP by a developer
- Query Loop block: set up in the editor with settings and nested blocks
The Query Loop block documentation on WordPress.org shows each of its settings.
Block themes don't use PHP template files for layout, so they rely on the Query Loop block instead. Our guide to the WordPress Query Loop block covers how it works.
If you're comparing theme types, our article on the WordPress block editor gives more background.
What mistakes do people make with the loop?
The most common mistakes are forgetting wp_reset_postdata after a custom loop, using query_posts, calling template tags outside the loop, and running heavy queries inside a loop.
Watch for these:
- No reset after a custom loop. Later content shows the wrong post.
- Using query_posts. It breaks pagination and doubles the database work.
- Template tags outside the loop. They may return the first post or nothing.
- Queries inside a loop. Running a new query for every post can slow pages badly.
- Editing parent theme files. Updates wipe your changes, so use a child theme.
If a loop change breaks your site, turn on debug mode to see the error. Our guide on enabling debug mode in WordPress shows how.
Do you need to understand the loop to use WordPress?
No, most site owners never touch the loop, but knowing what it is helps you understand themes, customise templates and talk clearly with developers.
If you only write content and use page builders or block themes, the loop works quietly in the background.
It becomes useful when you:
- Build or edit a classic theme
- Add related posts or custom lists in PHP
- Debug why the wrong posts appear on a page
- Write a plugin that changes how posts are shown
WordPress is built on PHP, and the loop is one of the first PHP ideas theme developers learn. Our explainer on whether WordPress is written in PHP covers the wider picture.
Frequently asked questions
Is the WordPress loop the same as a PHP loop?
It's built from a normal PHP while loop, but it uses WordPress functions such as have_posts and the_post to step through posts from a query. So it's a PHP loop with a specific WordPress job.
Can I have more than one loop on a page?
Yes. The main loop shows the page's main content, and you can add custom loops with new WP_Query for extra lists. Reset post data after each custom loop so the rest of the page works correctly.
Why shouldn't I use query_posts?
query_posts replaces the main query after it has already run, which wastes database work and often breaks pagination. Use pre_get_posts to change the main query, or new WP_Query for a separate list.
Do block themes use the loop?
Block themes don't use PHP template loops for layout. They use the Query Loop block, which runs the same kind of WordPress query behind the scenes and repeats a post template for each result.
Where do I edit the loop in my theme?
In a classic theme, the loop is in template files such as index.php, single.php and archive.php. Copy the file into a child theme before editing so updates don't overwrite your changes.
Sources
- The Loop WordPress Theme Handbook
- WP_Query class WordPress Developer Resources
- pre_get_posts hook WordPress Developer Resources
- while PHP Manual
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


