How to Use WP_Query to Display Custom Post Type

Using WP_Query with Custom Post Types

As a WordPress Developer, you might be asking yourself “How do I display a list of posts from a custom post type on my homepage?” Maybe you want to simply display the custom post title and a link back to the custom post for something like a blog page. Or perhaps you want to present a wide range of dynamic content with custom fields, images, etc. The powerful WP_Query class makes fetching and outputting your posts on your website a breeze, and we’re about to show you how it’s done!

WP_Query is a class used in WordPress theming that accepts a variety of parameters to request and fetch posts around those parameters. The example below allows you to set a list of parameters, fetch the posts matching those parameters, and display the title and excerpt of the post on the website. Let’s take a look at the example below using these steps.

1. Set up a variable that contains an array of parameters you’ll pass to the WP_Query class. You’ll want to set the ‘post_type’ parameter to the slug of the custom post type we’d like to query. Most likely, this is the custom post type that you’ve created already. If you haven’t created a custom post type yet, see how to create custom post types in WordPress.
2. Set the parameter ‘post_status’ to ‘published’ which will ensure the requested posts are published and not in a ‘draft’ state. If you wanted to get unpublished posts, you could easily set this to ‘draft’ or any of the other post status parameters.
3. Set the number of posts you’d like to fetch and return using the parameter ‘posts_per_page’.
4. The last parameters you’ll want to add are ‘orderby’ and ‘order’. The first parameter ‘orderby’ orders the posts by title, the second parameter ‘order’ orders all post ascending by the title or the ‘orderby’ parameter. After you’ve completed setting up the parameters, pass them into the WP_Query class and set the result to a variable. Then, go into the classic WordPress while loop to cycle through the resulting posts and display the title and excerpt using the template tags, the_title() and the_excerpt().

Don’t have the time to learn the ins and outs of WordPress WP_Query? Our team of professional web developers are ready and eager to work with you on the design and development of your website.

Start Improving My Website Now

WP_Query Custom Post Type Examples

The First Example

/**
 * Setup query to show the ‘services’ post type with ‘8’ posts.
 * Output the title with an excerpt.
 */
    $args = array(  
        'post_type' => 'services',
        'post_status' => 'publish',
        'posts_per_page' => 8, 
        'orderby’ => 'title', 
        'order’ => 'ASC', 
    );

    $loop = new WP_Query( $args ); 
        
    while ( $loop->have_posts() ) : $loop->the_post(); 
        print the_title(); 
        the_excerpt(); 
    endwhile;

    wp_reset_postdata(); 

The Output

If you were to run this query within your WordPress template, the output may look as follows:

Article Title
Example excerpt of the article.. Read More

A More Advanced Example

If you take a look at our next example, you’ll see it is slightly more advanced. We have added a category parameter to filter on posts with the category of ‘home’. In the output, you will see we’ve also added in our loop to get the featured image that’s attached to the post and display it with the title and excerpt. This more advanced example is to show you how powerful the WP_Query can be.

/**
 * Setup query to show the ‘services’ post type with all posts filtered by 'home' category.
 * Output is linked title with featured image and excerpt.
 */
   
    $args = array(  
        'post_type' => 'services',
        'post_status' => 'publish',
        'posts_per_page' => -1, 
        'orderby' => 'title', 
        'order' => 'ASC',
        'cat' => 'home',
    );

    $loop = new WP_Query( $args ); 
        
    while ( $loop->have_posts() ) : $loop->the_post(); 
        $featured_img = wp_get_attachment_image_src( $post->ID );
        print the_title();
        if ( $feature_img ) {
           < img src="print $featured_img['url']" width=”print $featured_img['width']" height="print $featured_img['height']" />
        }
        the_excerpt(); 
    endwhile;

    wp_reset_postdata(); 

Parameters

There are many parameters you can use to customize the requested posts with WP_Query. We cover some of the commonly used parameters below but for a more thorough list, take a look at the class reference WordPress Codex on parameters.

• cat - filters posts by a specific category id
• tag - filters posts by a specific tag slug
• tax_query - filters posts by specific taxonomy parameters
• s - filters posts by a search keyword
• Author - filters posts by a particular author

Template Tags

Within your custom post type loop, there are many Template Tags you can use inside the loop to output information dynamically. Some examples of other template tags you can use inside your loop:

• the_content() - Displays the content of a post
• the_permalink() - Displays URL of a post
• get_the_ID() - Retrieves the ID of a post
• home_url() - Retrieves the home URL

Now that you understand the basics of WP_Query and requesting and fetching your custom post type, you can use what you’ve learned to develop your own custom post type templates with an array of different parameters and template tags to display your custom posts easily to visitors.