How to Use the Query Posts Plugin

Query Posts plugin author Justin Madlock states “The Query Posts widget was written to allow users that don’t know their way around PHP to easily show posts in any way they’d like. It’s like having a cool WordPress developer as a friend ready to do your bidding.” I agree. It takes many of the parameters of the query_posts() function in WordPress and allows you to configure them by checking boxes and choosing list items. But like any full-featured piece of code, it has a bit of a learning curve. However, when you get it to work, it is enormously rewarding. I’d like to walk you through just one way you can use this plugin to direct some traffic to your older posts.

Get the Readme File

When you install and activate the plugin, a very helpful file is also uploaded in the same folder. The easiest way to access this file is to open a new browser tab and point it to, replacing with the url to your WordPress install. It should come up nicely formatted, giving a brief description of each option in the widget. I used it to learn how to configure the widget. Bookmark it so you can find it again.

Create a Category Widget

After you’ve been blogging for a while, you create a body of work that disappears into the archives. Your longtime readers may have seen it, but new visitors don’t know it’s there, and probably won’t go looking for it unless you give them a reason to. We’re going to create a sidebar widget that displays posts from a specific category.

The first step is to go to your Widgets subpanel under Appearance. Locate the Query Posts widget under Available Widgets and drag it into a sidebar. Immediately it pops open and offers you a plethora of options:

Query Posts WordPress widget opening screen

Click the image for a larger view

Wait! Come back! You can do this. Let’s just take this one step at a time.

Widget Title, Order, Order By

query posts plugin for wordpress The first field is labeled Title. Type in what you want your widget to be called when viewed on your sidebar. I’m going to call mine Query Posts Plugin Demo. Order and Order by go together. You’re going to create a list–how do you want that list ordered? By date? By number of comments? There’s a huge list to choose from. And once you’ve decided on what determines the order, it’s a simple matter to decide ascending or descending. I’m going to stick with the defaults: Date for Order by, and Descending for Order. So far, so good.

Post Status

post status option of query posts plugin for WordPressNext, what kind of posts do you want to display? You would think Published would be the only logical choice, but what if you were the really organized type, and wrote your posts ahead of time and scheduled them? You could have a sidebar that said Coming Soon and the titles of the posts you had scheduled. I can’t think of a reason to show your drafts, but maybe you can. Anyway, the choice is there if you want to. This is a multiple select box, which means you can select more than one choice. Hold done the Ctrl key as you click to choose more than one.

Post Type

post type option for query posts plugin in WordPressIn the same manner, you need to decide whether you want to display just Posts, just Pages, or Any that meet the other criteria your going to specify. For this particular example, I’m going to just display Posts. However, my gardening website,, has a lot of Pages, so I might want to include Pages as well in a widget there.

Individual Posts By ID

post option for query posts plugin for wordpressThe next two fields, Post and Category, are where some of the real power of this plugin shows itself. You can specify each post that you want displayed, if you want to hand pick them. Maybe you have some all-time greats buried in your archives that you’d like new readers to see. You have to identify the post by its number, which isn’t hard, but it isn’t obvious, either. Go to your Posts panel, and hover your cursor over the title of any post. While your cursor is over the post’s title, look down at the bottom of your browser window. You should see a url that has post=xxxx, where the x’s represent a number. That number is the post ID. If you have more than one post you want to display, separate them with commas when you enter them in the plugin’s Post field. As I said earlier, I’m going to make a Category widget, so I’m not going to specify any posts. I’m leaving it blank.

Post Category

category option for query posts plugin for wordpressThe Category field is one that I frequently use for my gardening blog. I have categories for certain types of posts, like book reviews or interviews, and I have categories for certain plants that I’ve written a number of posts about. I might display all my book reviews in the weeks leading up to the holiday gift-giving season. I know that I will get a lot of hits about pruning forsythia in mid-spring, so I try to make sure my Forsythia category is displayed in the sidebar at that time. I’m sure you can think of other uses. You find your category ID in a similar manner to finding the post ID, except this time, you guessed it, you go to the Categories subpanel under Posts. Hover your cursor over the category you wish to use, and look at the bottom of your browser window for the number. I am going to use the Image Handling category, which is 5.

Posts Per Page

posts per page option for query posts plugin for wordpressLet’s move to the top of the second column of options. Our first choice is Posts_Per_Page. I don’t have many posts in my sample blog, so I’m going to leave this at the default of 10. That means up to ten most recent posts that meet the other criteria will be displayed. In my gardening blog, which has well over one thousand posts, I set this to 15.


offset option for query posts plugin for wordpressOffset means number of posts to skip over before you start displaying. For example, I’ve got 20 posts in a gardening category, and I want to display 15. But the five most recent are, well, kind of recent, and they already show up in my Recent Entries widget. So I will set the offset to 5, and it will skip over the first five and start with the sixth. Now if I had set the order to show oldest first, then it would skip over the five oldest. Each of the options affects the other options.

Individual Page by ID, Post Tag

page and post tag options for WordPress query post pluginThere are a bunch of options I am going to skip, because they really don’t pertain to making a category widget. I will note that Page works in a similar fashion to Post, and Post_Tag works like Category does. If you wanted to show only posts from category X that were also tagged with Y, you could do that. But I don’t want to be that limiting here.


author option for wordpress query posts pluginMoving on to the third column, if you have a multi-author blog, you might want to show just one author’s contributions to a category. Again, you need to use the author’s ID, which is a number. If you’ve been following along, you’ve probably already surmised that you go to the Users subpanel, hover your cursor over the author’s name, and look down at the url in the bottom of your browser’s window for the number.


year and month options for wordpress query posts pluginThe Date fields would be another way to limit the number of posts in your category widget, say, only those in category X from a certain year. Or, if you weren’t limiting this widget to a certain category, you might only limit it by date. Every September, you could show all the posts from all the previous Septembers you had written posts for. Yes, you could specify the week, day, hour, minute, and second, but do you really want to? You may exclude all posts and show nothing in your sidebar if you’re not careful.

Sticky Posts, Reset Query, Display Widget Title

disable sticky posts option, reset query option for wordpress query posts pluginenable title option for wordpress query posts plugin optionLet’s quickly go through some more options. If you don’t disable sticky posts, they will still rise to the top of your list. Not sure what effect unchecking the Reset Query box would have, but since it’s working the way it is, I’m not going to change it. Attachments aren’t relevant to my category widget, but, moving to the fourth column of options, I do want to display a widget title (Query Posts Plugin Demo, remember?)

Entry Container

entry container option for wordpress query posts pluginEntry Container refers to the CSS that wraps every entry. According to the readme file, if you choose widget, each post appears as its own widget. Most sidebars use ul to list their items, so try that first. Skip over Post Class, unless you know you need it. Then think very carefully about whether you want to enable post thumbnails. If you are creating a sidebar widget, how much room do you really have for photos? If you are going to put this widget in a footer, it might work. Furthermore, if you don’t have the Get the Image plugin that Justin mentions in his readme file, and you don’t have featured images (formerly post-thumbnails) enabled in your theme, you will get a fatal error if you leave this box checked. (The worst thing that happens is the rest of your sidebar doesn’t load.)

Entry Titles

entry title option for wordpress query posts pluginThe entry title is the title of the individual blog post. First, make sure the box is checked if you want the titles of the posts to show. (If you uncheck the box, the following drop down list doesn’t pertain to you.) Then you need to decide what kind of styling to apply to the titles. This is a matter of trial and error, unless you are intimately familiar with the CSS of your site’s theme. On my gardening blog div seemed to work best, but on the demo site, using the new Twenty Ten default WordPress theme, no additional styling worked best.

Byline, Entry Content, More, Page Links, Entry Meta, Error Message

byline option for wordpress query posts pluginWe’re on the home stretch! Your choices for this column will determine how much of the posts will show. I only want a list of titles for my category widget, so I blanked out the Byline, the Entry Content, and the Entry Meta. When those are not used, the more code, and the page links have no effect. The error message won’t show unless the widget can’t find any posts that meet your criteria, so once you have successfully configured this widget, you should never see this message. I see no reason to change it.

Wrap Up

If you haven’t been doing so right along, click the save button in the bottom right corner of the widget, close it, and then view your site. Looking at the demo site, I see more space between the entries than I would like. I have looked at the page’s source code and can’t see any reason for why this should be. It looks right on my gardening site. I hope it will look right on your site, too. Keep in mind that some options can conflict with or modify other options if your widget doesn’t look as expected. The CSS of your theme will also affect the appearance of your widget. I suspect that is what is happening on my demo site. Any suggestions for a fix are welcome.

Comments on this entry are closed.

  • Thanks for a very useful writeup. Since I migrated my blogs from Movable Type to Wordpress I’ve hardly tinkered with them at all because it’s just so frustrating. The Query Posts Plugin sounds like a great tool.

  • Hello.

    I know this post is a couple of months old, but I wondered if you might be able to share some experience?

    I love this plugin and it is making one of my sites much more dynamic, based on the variables that I assign to the Query Posts Widget.

    However, my widget is pulling in titles and images from posts. Do you know how I can change the link that is displayed by the widget to point NOT to the post, but to a specific PAGE. All links will point to this one page, so if I change something in the code, that’s fine. It will never point to the posts.

  • If I correctly understand what you want to do, I don’t understand why you would use this widget to do it. If you want all links to point to one specific page, why not hard code the link and use a text widget?

  • Hi Kathy, and thanks for getting back to me.

    My reasoning is this. I have lights that are associated with specific buildings. For example, I have a few types of buildings; Hospitals, Warehouses, Schools etc. I create pages for each of these kinds of buildings. I also have lighting products that are suitable for specific buildings. When a visitor is on the Hospitals page, for example, they are shown lighting products that are only applicable to the hospitals. The way I tell the system (WP) which products are suited to what, is by creating a post per product and assigning it a category of ‘Hospitals’ or ‘Warehouses’

    There isn’t much more information on the product posts; just an image and title, which are pulled-in by the Query Post widget. The page I want to link to, needs to be a simple page that lists all of my lighting products, not just individual posts about one specific light.

    I hope that makes sense :0)

  • Oh… and I am also combining this widget with Widget Logic, so that the products only appear on the correct page :0)

  • I’m not sure I understand. It sounds like the pages are a listing of all posts that fall in a certain category, so they are category archive pages? I am not familiar with Widget Logic, and I’m not getting how this all works together.

  • Thanks for all this info. Do you have an easy method you could share, for embedding this widget in a post or page, rather than a wigetized sidebar. Any help would be appreciated.


  • Have you seen Widgetize This? Also did you see this video on Combining the Query Posts & Widget Logic Plugins with Widgetized Page Templates? I have not attempted this myself, but I found those two links from Justin Madlock’s page on the plugin.

  • Thank you so much for this! After the recent upgrade, I couldn’t figure out how to set the query for categories, and it seemed so cryptic.

  • Thank you for this helpful tutorial!
    I was struggling to get the list of entries to show the way I want, i.e. like with the previous version of the plugin, until I found your post.

  • Pedro Cassian

    Hi, I love this plugin, however I bought a premium theme and has a nice style for posts and I would like to retain that style, (yootheme – downtown btw)

    I´m wondering how I could take the query made in the widget and feed it to the theme´s loop, or If I could mimic the post´s style on the widget query

    Thanks in advance

  • Cheryl

    Hi, on the screenshot on the WP plugin directory it shows an cat__in and cat_and. They don’t come up when I installed it (or show in your screenshot). Do you know how to get posts that are in both of two categories (not all posts in the two categories) to show? e.g. only those that are in both ‘ballet’ and ‘city’ categories.


  • Wesley

    How would I get the text to wrap around the thumbnail in the displayed widget? Right now I currently have the image sitting above the text and it takes a lot of space. I am using the Get Image plug in that was suggested to pair with Query Post.

  • I’m using the Query Post plugin and it’s great, but I need to use it more than once. I have other categories i want in a separate widget. For instance, my first one is posts about writing, the second i want to do is posts about Relationships. How do i implement the use of this plugin more than once?

  • This worked well for using several widgets for different categories. But on the third widget, the category names began to appear below the title of the posts. This didn’t happen in previous two widgets with specific categories…i wonder if you had this problem? I can’t get it to stop showing the category names in text, and have compared all the entries in the setup to the previous two widget boxes, and all input is the same…Anyone?

  • UPDATE: figured out both my questions–in case anyone else was having the same problems…. on first (using the plugin more than once) It had to do with the fields i was filling in, of course. Had to make sure i had a different title and filled in the category NUMBER int he category box. Might have been something else, but now can’t remember. On the second issue (categories appearing below title) I had default code still in the entry_meta field. Taking that text out made the categories disappear on the widget when it appeared on the page/in the widget. Hope that helped someone else.