get_queried_object(): How and Why to Use It

WordPress’s get_queried_object() function has the distinction of being, I think, the most useful core function in WordPress that I didn’t know about for the longest time.

get_queried_object() has been in WordPress since 3.1, but I just learned about it in 2019. When I did, it was like a giant light bulb going off, because there’s just so much that get_queried_object() makes simpler in WordPress.

Don’t be like me! I’m here to spread the good news about get_queried_object(), and to help you understand how, when, and why to use it.

This article’s visually long (a lot of images), so here’s a navigation guide:

1. General description of get_queried_object().
2. What get_queried_object() returns on various kinds of webpages on your site.
3. Some practical uses of get_queried_object().

What get_queried_object() Does: It’s Fuzzy Thinking Time!

Before we go further: To understand the material below, you’ll want a basic understanding of WP_Query (enough to know what a “WordPress query” is in general), and of WordPress’s hooks system (specifically actions).

Turn your brain off and ask, “What is this page about?” get_queried_object() will give you that.

Okay, if we’re set there, then the best way to understand how get_queried_object() works is by following these steps:

1. Turn your brain off.
2. Ask “What is this page about?”
3. Think “get_queried_object() will give me that.”

It’s not just me being fuzzy: it’s actually about the level of detail in WordPress’s documentation. The official WordPress Function Library entry for get_queried_object() says the function’s behavior is to “Retrieve the currently-queried object,” lists its return value as “(object) Queried object,” and that’s it.

get_queried_object() retrieves the “thing” a given webpage on your site is “about,” and gives it back to you as a PHP object.

This fuzziness is partly because it’s best to think of get_queried_object() in a fuzzy way: somehow or another, it retrieves the “thing” a given page on your site is “about,” and gives it back to you as a PHP object.

The Four PHP Object Types get_queried_object() Can Return

Fortunately, the list of object types that a WordPress webpage can be “about” isn’t huge. In fact, there are only four:

1. A WP_Post Object.

On any webpage on your site that is generated by a single post of any post type—including Post, Page, or any custom post type—get_queried_object() will return the WP_Post object of that post.

If you have a Page designated as your website’s blog homepage (also called the blog index), get_queried_object() on that webpage will return the WP_Post object for that Page itself.

2. A WP_Term Object.

On a category archive, tag archive, or other taxonomy archive page, get_queried_object() will return the WP_Term object of the current category, tag, or other taxonomy term.

3. A WP_Post_Type Object.

On a post type archive page, get_queried_object() will return the WP_Post_Type object of that post type.

4. A WP_User Object.

On an author archive page, get_queried_object() will return the WP_User object of that author.

So those are the four options get_queried_object() can give you back, depending on what underlying object type provides the contents of the webpage WordPress is generating for display.

“Queried”: “Fetched from the Database”

One thing that may add clarity here: “queried” is a general term meaning “fetched from the WordPress database.” As we explain elsewhere, for any page on your website, WordPress needs to fetch a variety of stuff from the WordPress database to build that page.

What get_queried_object() gives you back is whatever the central element of that “variety of stuff” is, in whatever kind of PHP object it’s organized into.

get_queried_object() Examples: What It Returns on Different Webpage Types

The code of get_queried_object() itself couldn’t be simpler, as the function takes no arguments.

Understanding the function comes down to knowing what the function will return when called. If it runs successfully, you’ll always get back one or another kind of PHP object. In the get_queried_object() samples below, you’ll see what kind of objects you’ll get back in what situations, and what data those objects contain.

When You Call get_queried_object() Too Early

As a first note, you have to know when in WordPress’s hooks firing sequence to call get_queried_object(). In particular, if you call it too early, it won’t work.

In the below code example, we’re hooking our get_queried_object() call onto the init hook, which runs very early—before anything’s been queried.

add_action( 'init', 'wpshout_get_queried_object' );
function wpshout_get_queried_object() {
	var_dump( get_queried_object() );
}

The result is below: get_queried_object() returns null.

In other words, init is simply too early in WordPress’s lifecycle to call get_queried_object() and get anything back. In the code below, we hook onto a couple of different action hooks—the the_content and wp hooks, depending on what makes the var_dump in a given example easy to read. The common thread is that both those hooks fire late enough for the page’s key data to have actually been queried from the database.

get_queried_object() on Single Post (of Type Post)

Here’s the code to see what get_queried_object() gives us on the webpage that displays a single post of type Post:

add_action( 'the_content', 'wpshout_get_queried_object' );
function wpshout_get_queried_object() {
	var_dump( get_queried_object() );
}

And here’s what we get back:

The returned object is of type WP_Post, and contains all the data you’d need about the single Post that this webpage is built around.

As we’ll see, this is the exact same result you’ll get for Pages, and for posts of any custom post type.

get_queried_object() on Single Page

Here’s the code to see what get_queried_object() gives us on the webpage that displays a single post of type Page:

add_action( 'the_content', 'wpshout_get_queried_object' );
function wpshout_get_queried_object() {
	var_dump( get_queried_object() );
}

And here’s what we get back:

Again, the returned object is of type WP_Post, and contains data about the single post of type Page that this webpage is built around.

get_queried_object() on Single Post of Custom Post Type

Here’s the code to see what get_queried_object() gives us on the webpage that displays a single post from a custom post type, in this case “Custom Post”:

add_action( 'the_content', 'wpshout_get_queried_object' );
function wpshout_get_queried_object() {
	var_dump( get_queried_object() );
}

And here’s what we get back:

Again, the returned object is of type WP_Post, and contains data about the single post of type Custom Post that this webpage is built around.

get_queried_object() on Blog Index Page

Here’s the code to see what get_queried_object() gives us on the blog index page (the webpage that displays the site’s Posts):

add_action( 'wp', 'wpshout_get_queried_object' );
function wpshout_get_queried_object() {
	var_dump( get_queried_object() );
}

And here’s what we get back:

The returned object is of type WP_Post, and it’s telling you about the Blog Index Page itself—not the posts of type Post that display within it.

get_queried_object() on Taxonomy Archives

The following code will show us how get_queried_object() gives us back on a taxonomy archive page, which in this case is an archive page for the category “Test Category”:

add_action( 'wp', 'wpshout_get_queried_object' );
function wpshout_get_queried_object() {
	var_dump( get_queried_object() );
}

Here’s what we get:

This is an object of type WP_Term that tells us everything about the taxonomy term that this webpage is built around. Note the get_queried_object() doesn’t tell us about the two queried posts (“Single Post” and “Second Single Post”) that are members of that taxonomy term. Instead, it tells us about the term itself.

get_queried_object() on Author Archives

An author archive lists all posts from a single author. This code:

add_action( 'wp', 'wpshout_get_queried_object' );
function wpshout_get_queried_object() {
	var_dump( get_queried_object() );
}

Gives this result:

This is a WP_User object containing all the information you’d ever want about the author user itself. Again, get_queried_object() is telling you about the “thing” (a user) that this webpage is built around—not about the posts that are returned as belonging to that user.

get_queried_object() on Date Archives

This shows how get_queried_object() behaves on a date-based archive page—here, a monthly archive listing all posts from a single month.

Code is here:

add_action( 'wp', 'wpshout_get_queried_object' );
function wpshout_get_queried_object() {
	var_dump( get_queried_object() );
}

Oddly enough, this simply returns null:

Why do we get a null result? There is no such thing as a WP_Date object, nor are dates a taxonomy term, so there’s nothing for get_queried_object() to give back.

Practical Uses and Examples of get_queried_object()

Okay, that’s a lot of detail on what get_queried_object() does. What makes it useful? Below are a few practical examples.

Using get_queried_object() to Customize Archive Page Titles

Below is code that modifies part of the Twenty Nineteen theme’s archive.php template:

<header class="page-header">
	<?php $queried = get_queried_object(); ?>

	<?php if( get_class( $queried ) === 'WP_User' ) : ?>

		<h1>Super-Cool Stuff by <?php echo $queried->data->display_name; ?></h1>

	<?php else: ?>

		the_archive_title( '<h1 class="page-title">', '</h1>' );

	<?php endif; ?>
</header>

And here’s how an author archive page looks as a result:

How would we get the “Fred” piece of the above without get_queried_object()? There’d be some painful way to do it, but this is exactly what get_queried_object() is for.

Using get_queried_object() to Get a Count of Posts in a Taxonomy Term

So often in WordPress you’re using WP_Query to talk to bundles of WP_Post objects. When you want to talk to WordPress’s other data structures, get_queried_object() becomes extremely useful.

Below is a different modification to the Twenty Nineteen theme’s archive.php template:

<?php $queried = get_queried_object(); ?>

<?php if( get_class( $queried ) === 'WP_Term' ) : ?>

	<p><em>Just so you know, there are <?php echo $queried->count; ?> posts that belong to the term <?php echo $queried->name; ?>.</em></p>

<?php endif; ?>

And here’s how it behaves on a taxonomy term archive page:

Again, without talking to the taxonomy term, how would we ever get its count? And how do we know which one we’re talking to? There are painful ways to solve that problem, but it’s precisely what get_queried_object() is all about.

Using get_queried_object() to Add a Custom Title to a Custom Post Type Archive

Below is code applied to the functions.php file of the active child theme on our site Writers.com:

add_action( 'loop_start', 'wpshout_cpt_archive_demo' );
function wpshout_cpt_archive_demo() {
	if( ! is_archive( 'community_news' ) || ! is_main_query() ) :
		return;
	endif;

	$queried = get_queried_object();

	$count = wp_count_posts( $queried->name );
	echo '<h1>' . $queried->label . ' (' . $count->publish . ' entries)</h1>';
}

And here is the result on the post type archive page for the Community News custom post type:

Now You Understand get_queried_object()

get_queried_object() is the WP_Query for everything else on your site: taxonomy terms, users, and so on.

Hopefully the demos and practical examples above give you the general sense of get_queried_object(): it’s extremely useful for talking to whatever a given webpage on your site is about. Or, as I like to think about it, get_queried_object() is the WP_Query for everything else on your site: taxonomy terms, users, and so on.

Thanks for reading! If you have any questions or thoughts, leave them below, or we’d love to hear from you in our Facebook group.