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 this year, while browsing Stack Overflow answers about fetching taxonomy meta. Learning that WordPress had a function all ready to go was a bit like Googling for “how to break a coconut,” and learning that every home comes fully equipped with a Coconut Chisel in a special compartment under the kitchen sink.

Anyway, 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: this is actually about the level of detail in WordPress’s documentation.

The WordPress Function Library entry for get_queried_object() is almost entirely useless: it says the function’s behavior is to “Retrieve the currently-queried object,” lists its return value as “(object) Queried object,” and that’s literally it.

The Codex is a bit better. It lists some concrete possibilities for how get_queried_object() works:

• If you’re on a single post, it will return the post object
• If you’re on a page, it will return the page object
• If you’re on an archive page, it will return the post type object
• If you’re on a category archive, it will return the category object
• If you’re on an author archive, it will return the author object
• etc.

Helpful, but a lot of the wording isn’t accurate: there’s no such thing as a “post type object” in WordPress, for example—just a WP_Post object with a different post_type property. (And you have to love the “etc.” at the end.)

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

All this fuzziness is 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.

“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?

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.

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.

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.