WP_Query Arguments: Posts, Pages, and Post Types

In this part of this series on WP_Query, you'll learn how to use WP_Query to query for posts, pages, and custom post types. You can query for specific posts and pages or you can run a query to return posts of one or more post types.

A Recap on How Arguments Work in WP_Query

Before we start, let's have a quick recap on how arguments work in WP_Query. When you code WP_Query in your themes or plugins, you need to include four main elements:

the arguments for the query, using parameters which will be covered in this tutorial
the query itself
the loop
finishing off: closing if and while tags and resetting post data

In practice, this will look something like the following:

<?php

$args = array(
    // Arguments for your query.
);

// Custom query.
$query = new WP_Query( $args );

// Check that we have query results.
if ( $query->have_posts() ) {

    // Start looping over the query results.
    while ( $query->have_posts() ) {

        $query->the_post();

        // Contents of the queried post results go here.

    }

}

// Restore original post data.
wp_reset_postdata();

?>

The arguments tell WordPress what data to fetch from the database, and it's those that I'll cover here. So all we're focusing on here is the first part of the code:

1	$args = array(
2	// Arguments for your query.
3	);

As you can see, the arguments are contained in an array. You'll learn how to code them as you work through this tutorial.

Coding Your Arguments

There is a specific way to code the arguments in the array, which is as follows:

$args = array(
    'parameter1' => 'value',
    'parameter2' => 'value',
    'parameter3' => 'value'
);

You must enclose the parameters and their values in single quotation marks, use => between them, and separate them with a comma. If you get this wrong, WordPress may not add all of your arguments to the query or you may get a white screen.

Querying for Single Posts or Pages

Let's start with the simplest scenario: running a query to find a specific post or page.

Querying for One Post

To find a specific post (or set of posts), you have two options:

p (int): Use the post ID.
name (string): Use the post slug.

You can use these parameters with any post type including posts, pages, attachments, and custom post types. By default, WordPress will query for the 'post' post type and not return pages or custom post types—if you want to do this, you'll need to add more arguments or use a different argument, which I'll come to later in this tutorial.

So to return a specific post, you would use one of these:

1	$args = array(
2	'p' => 224
3	);

or:

1	$args = array(
2	'name' => 'how-to-create-a-website'
3	);

Note that the name parameter takes the post slug as its argument, not its title.

Using the name parameter makes it easier to identify what your query will fetch from the database when you revisit your code at a later date, but there is the risk that it won't work if one of your site's users changes the post slug. The post ID can't be changed, so this is safer.

Here is the result of running the above two queries for me.

Querying for One Page

To query for a specific page, you have two options again:

page_id (int): Use the page ID.
pagename (string): Use the page slug.

So to run a query fetching just one specific page from the database, you'd use one of these:

1	$args = array(
2	'page_id' => '20'
3	);

or:

1	$args = array(
2	'pagename' => 'domain-name-generator'
3	);

You might have noticed that we passed 20 as a string to page_id in our example. This 20 is cast to an integer because page_id expects the parameter to be an integer.

I got the following pages back by running the above queries.

Querying for One Post of Another Type

To run a query for a post of another post type, including a custom post type, you'd also use the post_type parameter. I'll cover this in a bit more detail later in this tutorial, but in brief, to query for a single post in the product custom post type, you'd use this:

1	$args = array(
2	'p' => '46',
3	'post_type' => 'product'
4	);

Or to query for an attachment, you'd use:

1	$args = array(
2	'p' => '248',
3	'post_type' => 'attachment'
4	);

I get back an image if I run the second query.

Querying for Child Pages

Sometimes, you might need to retrieve all pages that are children of a given page—for example, if your site has a hierarchical page structure and you want to display a list on each page of that page's children.

You wouldn't do this with posts as they aren't hierarchical, although you can with a custom post type if it's hierarchical.

You have three arguments you can use to do this:

post_parent (int): Use page ID to return only child pages. Set to 0 to return only top-level entries.
post_parent__in (array): Use an array of post IDs.
post_parent__not_in (array): Use an array of post IDs.

Let's take a look at each of them.

The first, post_parent, lets you query for pages which are children of a specific page.

So to find all pages that are children of a given page, you'd use this:

1	$args = array(
2	'post_type' => 'page',
3	'post_parent' => '2'
4	);

Note that you have to include the post_type argument as the default post type that WP_Query looks for is post.

Taking this further, this is how you'd use it to find children of the current page:

$current_page_id = get_the_ID();

$args = array(
    'post_type' => 'page',
    'post_parent' => $current_page_id
);

You can also use this parameter to identify top-level pages, i.e. those without a parent:

1	$args = array(
2	'post_type' => 'page',
3	'post_parent' => '0'
4	);

But what if you want to identify children of multiple pages? You can do this too, with the post_parent__in parameter. This takes an array of post IDs.

So to query for the children of two of your pages, you'd use this:

$args = array(
    'post_type' => 'page',
    'post_parent__in' => array(
        '2',
        '4'
    )
);

You can also exclude child pages from your query, using the post_parent__not_in parameter:

$args = array(
    'post_type' => 'page',
    'post_parent__not_in' => array(
        '2',
        '4'
    )
);

Querying for Multiple Posts

It's also common to run a query to either include or exclude multiple posts. You have two arguments you can use for this:

post__in (array): Use post IDs.
post__not_in (array): Use post IDs.

The post__in argument can be used for all post types and takes an array of IDs. So to output a list of specific posts, you'd use this:

1	$args = array(
2	'post__in' => array(
3	'704',
4	'224',
5	'218',
6	'152'
7	)
8	);

You might have noticed that the list of retrieved posts does not include posts with IDs 704 and 224. This is because WordPress will only fetch published posts by default. It is possible to retrieve posts with different statuses by setting the value of the post_status argument to 'any'. You can learn more about this argument and its possible valid values in this tutorial.

1	$args = array(
2	'post__in' => array(
3	'704',
4	'224',
5	'218',
6	'152'
7	),
8	'post_status' => 'any'
9	);

You're probably also wondering about the first post in the retrieved list. Please note that if you use the post__in argument to fetch posts, WordPress will still fetch sticky posts, even if they're not in your list, as you can see in the image above. To omit them, you use the ignore_sticky_posts argument:

$args = array(
    'post__in' => array(
        '704',
        '224',
        '218',
        '152'
    ),
    'post_status' => 'any',
    'ignore_sticky_posts' => 'true'
);

The post__not_in argument works in a similar way, again taking an array of post IDs, but it will output everything except the posts listed. You'd normally combine it with other arguments to avoid outputting a huge list of posts.

Keep in mind that you cannot use both post__in and post_not__in in the same query.

So to query for all posts of the product post type but exclude a few:

$args = array(
    'post_type' => 'product',
    'post__not_in' => array(
        '36',
        '52',
        '246',
        '354'
    )
);

So to combine this with one of our earlier examples, here's how you'd query for all top-level pages except the current one:

$current_page_ids = array( get_the_ID() );

$args = array(
    'post_parent' => '0',
    'post__not_in' => $current_page_ids
);

Note that if you've also registered a hierarchical post type, you'll need to include the post_type parameter in this code to just query for pages.

Querying for Post Types

In some of the examples above, I've used the post_type parameter to identify posts of a certain type. Let's take a look at the arguments you can use with that parameter:

post: A post.
page: A page.
revision: A revision.
attachment: An attachment.
nav_menu_item: A navigation menu item.
any: Retrieves any type except revisions and types with 'exclude_from_search' set to true when they were registered.
Custom Post Types (e.g. product).

As we've seen above, you can use this parameter with other arguments to make your query more specific.

The value for post_type is usually set to post by default. However, it becomes any whenever you use the tax_query argument in your queries.

To give a simple example, here's how you'd query for all of your site's pages:

1	$args = array(
2	'post_type' => 'page'
3	);

Custom Post Types

Querying for a custom post type is simple: use the name you gave the post type when registering it, not the title that's used in the admin menus. So let's say you registered your product post types using register_post_type() as follows:

function register_product() {

    $args = array(
        'name' => __( 'Products', 'tutsplus' ),
        'singular_name' => __( 'Product', 'tutsplus' )
    );

    register_post_type( 'product', $args );
}

The value you use for the post_type argument when querying for products isn't 'Product' or 'Products' but 'product':

1	$args = array(
2	'post_type' => 'product'
3	);

Attachments

By default, if you try to run a query for attachments, it won't work. That's because WordPress sets the post_status of attachments to inherit and WP_Query defaults to 'post_status' => 'publish' unless you specify otherwise. So if you want to query for attachments, you must include the post_status argument:

1	$args = array(
2	'post_type' => 'attachment',
3	'post_status' => 'inherit'
4	);

Note that you could also use any instead of inherit.

Summary

Using WP_Query to create custom queries for posts and post types is something I do a lot. As you've seen from the examples here, there are plenty of possibilities:

Use it to query for top-level pages in your site.
Use it to query for posts of a specific post type.
Use it to query for all posts except the ones you specify.
Use it to query for all the children of the current page.

There are many more possibilities using the arguments covered here, but this should give you a taster.

This post has been updated with contributions from Nitish Kumar. Nitish is a web developer with experience in creating eCommerce websites on various platforms. He spends his free time working on personal projects that make his everyday life easier or taking long evening walks with friends.