Display Posts Shortcode

The Display Posts Shortcode was written to allow users to easily display listings of posts without knowing PHP or editing template files.

Add the shortcode in a post or page, and use the arguments to query based on tag, category, post type, and many other possibilities.

For full documentation and examples, see the Display Posts Shortcode Wiki. I also have some code snippets that extend this plugin, which are good examples if you’re looking to do something similar.

Comments are closed. Please post all questions on the Support Forum.

Bill Erickson

Bill Erickson is the co-founder and lead developer at CultivateWP, a WordPress agency focusing on high performance sites for web publishers.

About Me
Ready to upgrade your website?

I build custom WordPress websites that look great and are easy to manage.

Let's Talk

Reader Interactions

Comments are closed. Continue the conversation with me on Twitter: @billerickson


  1. Mark says

    I just wanted to say thank you for this code. It took some searching, but luckily I landed on your page. Nicely done.

  2. Josh says

    Nice. Good job. The only thing I would also like is to have the option to add the excerpt as well.

      • Paula says

        Have you added the excerpt option to the plugin as yet? If yes, how do you actually add the excerpt. I have typed in “include_excerpt=” as part of my shortcode but not sure what to put after the equals sign.

        • Bill Erickson says

          No, the excerpt is currently not a feature. When I get a chance to release the next version of the plugin, it will included the excerpt and post type.

  3. Clay says


    I see in the Codex where it should be possible to ‘AND’ multiple tags.

    $query = new WP_Query( ‘tag=bread+baking+recipe’ );

    Is this supported in the shortcode?

    :: Clay

    • Bill Erickson says

      I just tested it and it works. You can use + as an AND operator and , as an OR operator.

      • Clay says

        Thanks for the prompt reply. Not sure why it wasn’t working for me earlier, it now does. Perhaps a cache issue – something I do need to check for more diligently.

        Overloading this thread with some new questions …

        1) Where is the CSS for formatting the return? Because I am displaying thumbnails, I don’t need the bullet in the unordered lists and the post title is bottom aligned with the thumbnail?

        2) Is there a (simple) way of specifying the max number of characters returned in the excerpt?

        3) Then inserting a line break after the post title to start the truncated excerpt on the next line.

        :: Clay

        • Bill Erickson says

          1. There currently isn’t any CSS, but you can write your own using the classes that are applied to every element.

          2. You can modify the excerpt length site-wide by using the excerpt_length filter. Or you could shorten it just here by filtering the whole output and changing $excerpt in some way (see the code in further customizations).

          3. You could do this with CSS by setting .display-posts-listing .title {display:block;} or you could use the output filter to manually add a line break to the output.

          • Clay says

            As I am not adept at PHP (and I do have a client for this and it would probably cost them more for me to fumble around with this until I figured it out), what would a ballpark charge be to make a custom output filter that would let me tailor excerpt length by changing a variable, etc?

          • Clay says

            Bill – That’s very gracious of you. Thank you.

            One final set of questions as this pushes the limit of my present understanding. I have downloaded the code from github but don’t immediately see how to incorporate it into the original shortcode code. I see where a filter is referenced in the original file but am I copying this code into that file, linking to the filter which is stored in the same directory as the original shortcode?

            It also looks like the “50” in the following

            be_truncate_phrase( get_the_excerpt(), 50 )

            Is the magic number I use to determine the amount of text displayed.

            Again, TIA,
            :: Clay

        • Bill Erickson says

          Sorry I wasn’t clearer. That code can be added to your theme’s functions.php file. The filter allows you to modify the plugin without actually editing the plugin files. That way when the plugin is updated in the future your changes don’t get overwritten.

          There’s two functions in there. The function that actually modifies the shortcode, and the function to truncate the phrase. I actually copied this function out of Genesis, so if you’re using Genesis you don’t need to add the second function and can modify the first to use genesis_truncate_phrase() instead of be_truncate_phrase().

          Yes, 50 is the magic number.

  4. Clay says

    Bill –
    Traveling back from Dallas yesterday. Cut and paste the filter code on github into functions.php and get the following error:

    Fatal error: Call to undefined function add_filter() in /…path…/wp-includes/functions.php on line 4567

    • Bill Erickson says

      Are you running the latest version of the plugin? I just added the filter a few days ago.

      • Clay says

        Running v 1.5 according to the installed plugins dashboard. File dates on the unzipped archive are 8/27 @ 8:22PM

        • Clay says

          Bill –

          Thanks for all your behind-the-scenes patience and good will. My mistakes, not being fully aware of the folder/file structure of WP.

          Works like a charm.

          :: Clay

  5. James Wellington says

    First off, thanks for the plugin! Was able to get everything working except for sorting. I am trying to display a list of pages ordered by menu order, order ASC. Here is the shortcode I am using…

    [display-posts post_type="page" taxonomy="attraction-type" tax_term="Lighthouses" image_size="Attraction List" orderby="menu_order" order="ASC" ]

    Am I missing something? I just can’t get them to sort properly.

    • Bill Erickson says

      Everything looks right to me. I’ll have to do some testing to see if there’s a conflict with taxonomy queries and sorting. Does it sort correctly if you leave out the taxonomy and tax_term arguments?

      • James Wellington says

        Thanks for the reply Bill. I went ahead and removed the custom taxonomy and tax_term arguments as requested and it sorted properly. [display-posts order="ASC" orderby="menu_order"]

        I’ve come across another hang-up as it seems to mess with the site template I’m using. I had to disable all plugins to identify which plugin was the culprit, unfortunately Display Posts Shortcode was it. The specific conflict i am having with the template is the home page feature banner. The theme has an option to feature pages or posts. I’ve selected pages but after activating this plugin it displays both, pages and post. The post have images not formatted to 1400 x 300 so it makes the entire homepage look like garbage.

        Sorry to spring the second issue on you. I’ve tried looking for other solutions but this seems to be the only plugin that will display both post types using custom taxonomies in a fashion that works for us.

        Thanks again

  6. Nurdan says

    Hello 🙂 I was wondering if there was a way to add custom fields. I am using ADV custom fields plugin and would like to add 3 custom fields below the title to output for each post listed. I am not a programmer so therefore i would be ever so grateful if you could help. Thank you very much in advance!

    This is the code of php I have to insert below the title of the post. But I don’t know where to place it for it to show.

    So it would go:

    • Bill Erickson says

      Yes, this is what the “further customizations” section shows how to do. Use the filter to modify the output of the shortcode.

      Here’s code that shows specifically how to do what you’re looking for: https://gist.github.com/1209601

      Things you might need to change:
      – Name of custom fields (I used location, type and price)
      – HTML wrapping each custom field (I used span’s)
      – Order in which everything is output

      If you need help with further customization I recommend you hire a developer.