WordPress Loop – The Complete Guide For Developers

WordPress Loop - The Complete Guide for Developers

WordPress Loop is a PHP code which displays posts or pages content on your WordPress website. Most of the time WordPress loop is used to show the post/page title, excerpt, and content on the blog listing page.

WordPress Loop is the heart of WordPress website and your website won’t function at all without it. In this post, we will explore what is WordPress loop, where it needs to be in your WordPress theme and how we can customize it.

Let’s start by exploring What is WordPress Loop?

What is the WordPress Loop?

The WordPress Loop is a small piece of PHP code which grab the data from the database and then display it. The output we get from this loop is a mix of PHP code and some HTML.

WordPress calls it the loop because it loops, which means it repeats itself until nothing left to show on your website. When we call WordPress loop on a single page template, it repeats itself only once.

On pages like archive, category, and index, it repeats itself until it reaches the last record from the database. The type of data we get from a loop depends on the nature of post format we are using which will include data from the database and some helper functions.

Logic Behind WordPress Loop

If you want to build better WordPress themes then you need to understand how WordPress loop functions. This loop starts with code which checks whether the current page should load a single post or multiple posts, it depends where you are running this loop.

If a page supposes to list multiple posts like on archive or category page, then this loop will render the post title and excerpt while you can access other post related data like feature image, published date etc on the fly.

If the page supposes to show a single post like on a custom page template or single template, then it will render post title and content.

If there are no posts found in the loop then, we can pass a custom message to show visitors that there is no data to show (404 page).

You can also run multiple loops on the same page if you are loading different type of data or dealing with custom post types.

Where You Can Find it?

We can find a loop in almost all template files of WordPress. In some cases, there will be template parts being used to load different section of the website.

A template part file is a piece of code which we can use throughout our website repeatedly. So instead of running a loop, again and again, we run loop once and load different templates based on the types of post.

Let’s take a look at the Twenty Seventeen theme which shipped by default with WordPress.

Here is the file structure for Twenty Seventeen theme.

Twenty Seventeen Theme File Structure
Twenty Seventeen Theme File Structure

You can see there a bunch of different template files.

  • 404.php
  • archive.php
  • index.php
  • page.php
  • single.php

and others.

You can see in the above image, there is a template parts directory which holds all template parts for this theme.

  • content-front-page.php
  • content-page.php
  • content.php
  • content-audio.php
  • content-excerpt.php
  • content-image.php
  • content-none.php
  • content-video.php

There are more template parts in this folder which may have been called on different places within this theme.

Let’s explore the WordPress Loop example, by opening the page.php file.

Here is the code extracted for this file.

When looking for a loop in any WordPress template, you should find this line of code:

while ( have_posts() ) : the_post();

This is the line where loop start and this line close the loop.


Above code example doesn’t include the HTML that displays a WordPress post, instead, it’s including a template part (content-page.php) using method get_template_part(). This function fetches the content of the template part and renders it here in the template.

Now we move on and look at the code of the content-page.php file.

We will go through the above code line by line.

Firstly, this file opens an article element and output the post title inside anheader element. This article element also has an ID that use the the_ID() template tag to grab the current post id and similarly class use the post_class() template tag to add the class of current post.

This will add the unique id for this post and class with taxonomies details into the article element.

A header element is then opened, which shows the post title using the_title() template tag. Then the header element is closed.

Now this will show the content of the post using below code.

Here we will break it down in small steps.

  1. 1. Firstly, it opens a div element with class entery-content.
  2. 2. Then it uses the the_content() template tag to show the content of the post.
  3. 3. Then it uses the wp_link_pages template tag to display links to earlier and later posts.
  4. 4. It closes the entery-content div.

Finally, the article element that contains everything is closed.

What a Loop can provide?

There are numbers of different elements which you can get from a loop such as a title, content, feature image, published date, taxonomies etc.

Below you can find a list of most commonly used functions, which can be used within a loop.

  • the_title: Displays the title of post or page.
  • the_time: Displays the time or date for post or page when it was published.
  • the_content: Displays the content of post or page.
  • the_tags: Displays the tags associated with the post.
  • the_author: Displays the author of the post.
  • the_excerpt: Displays the first 55 characters of post or page with a read more link.
  • the_ID: Displays the unique id of the post of the page.
  • the_meta: Displays custom fields attached to a post or page.
  • the_category: Displays the categories of the post.
  • next_post_link: Displays a link to the next post.
  • previous_post_link: Displays a link to the previous post.

This loop can also use the number of different conditional functions to display different content based on numbers of factors. Such as…

  • is_home(): Returns true if current page is a homepage.
  • is_admin(): Returns true if an admin is logged in.
  • is_single(): Returns true if a page is displaying a single post.
  • is_page(): Returns true if a page is displaying a single page.
  • is_page_template(): Returns true if a page is using a specific template part.
  • is_category(): Returns true if a page or post has a specified category like is_category(‘WordPress’).
  • is_tag(): Returns true if page or post is using a specified tag.
  • is_author(): Returns true if a specific author is logged in.
  • is_search(): Returns true if a page is a search page.
  • is_404(): Returns true if a page does not exist.

Running Multiple WordPress Loops

When you are creating a premium WordPress theme, you will run into a situation where you have to write multiple loops on a single page. In that case, you have to rewind or rest the current loop to start again, before starting any other new loop.

Below is the WordPress loop code which will rewind the first loop and you can start a new loop just after the first one.

Have a close loop on line 7 where we are using the rewind_posts() function.

Above code example has one issue, as it will always return the same data and we are just looping on that data. In a real-time situation, we might want to have different data for our next loop.

We can customize the data of a loop using query_posts() function by passing some custom parameters to modify our loop data.

For example, we want to show the first three posts as the latest posts in the different template and rest of the posts will follow in the normal posts listing template.

In the above code example on line 1 and 11, we are passing custom query parameters to change the loop’s data. We are requesting to show three posts where post type is post, on line 1 and on line 11, we are offsetting first three posts and getting rest of the posts.

Loop with WP Query

To get the full control on customizing the loop, WordPress provides a very powerful function called WP_Query. In the previous section, we used query_posts() function which is a part of WP_Query() function.

For better understanding, let’s use the WP_Query() function to grab all posts of a specific category.

This function takes the same parameters as query_post, we can customize the loop data by setting various parameters like below.

We can combine the parameters same as we did in query_post() function. To get the same results as we did in the previous section, we will write the WP_Query function something like below.

$custom_query = new WP_Query('posts_per_page=3&cat=3&order=ASC');

You should always use WP_Query() function when you need to run multiple loops and want to customize the output of data.

Here are a few of the most commonly used WP_Query options.

  • author: Filter all posts by author id
  • cat: Filter all posts by a category id
  • category_name: Filter all posts by a category slug
  • tag: Filter all posts by a tag slug
  • name: Filter loop by post slug
  • pagename: Filter loop by a page slug
  • page_id: Filter loop by the id of a page
  • post_type: Filter loop by post type including custom post types
  • post_per_page: Define how many posts to add in the loop
  • offset: Define how many posts to offset
  • order: Determines whether to show posts in ascending or descending order
  • orderby: Order loop’s data by a post data like by default it orders it using date

How WordPress Loop will Help You?

To build a WordPress theme, you need to have a better understanding of how WordPress loop work. You can not build a theme without using the WordPress loop. WordPress loop can be customized in any way to grab the data you are looking for.


In this post, We found that how we can use a WordPress loop and how we can customize it. In nutshell,

  • When you want to change the default loop, use post_query() function
  • If you are running multiple loops or want to modify them use WP_Query() function

If you have any question or suggestion to improve this post, please let us know in the comment box below.

You May Also Like

About the Author: WebWhistles