Bill Erickson edited this page Nov 16, 2018 · 57 revisions

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 (see the Arguments). I've also added some extra options to display something more than just the title: include_date, include_excerpt, and image_size.

Table of Contents


[display-posts tag="advanced" posts_per_page="20"]

This will list the 20 most recent posts with the tag 'Advanced'.

[display-posts tag="advanced" image_size="thumbnail"]

This will list the 10 most recent posts tagged 'Advanced' and display a post image using the 'Thumbnail' size.

[display-posts category="must-read" posts_per_page="-1" include_date="true" order="ASC" orderby="title"]

This will list every post in the Must Read category, in alphabetical order, with the date appended to the end.

[display-posts taxonomy="color" tax_term="blue" include_excerpt="true"]

This will display the title and excerpt of the 10 most recent posts marked "blue" in the custom taxonomy "color".

[display-posts wrapper="ol"]

This will display posts as an ordered list. Options are ul for unordered lists (default), ol for ordered lists, or div for divs.

[display-posts id="14,3"]

This will display only the posts with an ID of 14 and 3.

Available Parameters

Extension Plugins

These are plugins that add additional capabilities to Display Posts Shortcode

If you have an extension you'd like included here, please submit it for review.

Customization with Filters

Filters allow you to place code in your theme or a plugin that modifies how Display Posts Shortcode works. If this is for a single website, I recommend you put it in a Core Functionality plugin.

If it can be generalized and useful to others, I recommend you write it as an extension plugin and submit it for review. See current extension plugins.

Change the default arguments of the shortcode. For instance, if you want all shortcodes to have include_excerpt="true" and include_author="true", you could use this to set it once and then not have to include those parameters on all shortcodes.

For customizing the $args passed to WP_Query. Useful if a query arg you want isn't already in the shortcode.

For customizing the message displayed if no posts are found. Default is empty, but can be specified in shortcode: [display-posts no_posts_message="message goes here"]

Filter the HTML markup for the author if [display-posts include_author="true"]

For customizing the list of categories if [display-posts category_display="true"]

For adding classes to the individual posts (ex: break into columns)

Example: For customizing the output of individual posts.

display_posts_shortcode_wrapper_open and display_posts_shortcode_wrapper_close
For customizing the outer markup of the whole listing. By default it is a ul but can be changed to ol or div using the 'wrapper' attribute, or by using this filter.

Modify what heading tag is used for display posts title if [display-posts title="Recent Posts"]. Default is h2

Filter the sanitize segments for the given date or time string, for date queries.

When [display-posts include_content="true"], we disable any display posts shortcodes within that content from running to prevent infinite loops. If you are SURE you won't get an infinite loop and want the shortcode to run, use this filter to override it.

Core WP filters used

excerpt_length (unless the excerpt_length or excerpt_more parameters are specified in shortcode)
excerpt_more (unless the excerpt_length or excerpt_more parameters are specified in shortcode)

More examples:

Using Template Parts

If your theme uses template parts for post output already, you can leverage those same template parts when using this shortcode. You'll use the display_posts_shortcode_output filter to modify the plugin output, using the partial you prefer.

There are many methods you can use for determining what partial to use. Three common approaches are:

  1. Based on the post type of the post you're displaying. Example
  2. Based on some other attribute we're querying. Example
  3. Based on a custom attribute you define. Example

More information in this tutorial: Template Parts with Display Posts Shortcode

Popular Posts

There are many ways to display most popular posts – you need to decide what method works best for you.

If you want to use “comment count” as a proxy for popularity (the most popular posts have the most comments), you can sort by comment count like this:

[display-posts orderby="comment_count" order="DESC"]

If you want to use social sharing (like Facebook likes), first install EA Share Count and use that for your social sharing buttons on your site, then use this shortcode:

[display-posts orderby="meta_value_num" meta_key="ea_share_count_total" order="DESC"]

If you want to use pageviews, first install Jetpack, enable the Site Stats module, then install BE Stats, and then use this shortcode:

[display-posts orderby="popular"]

Image Alignment

A common request is display a list of posts with title, excerpt, and the thumbnail aligned to the left. Here's the shortcode you might use:

[display-posts include_excerpt="true" image_size="thumbnail" wrapper="div"]

This includes the excerpt, adds an image of the "thumbnail" size (you can customize the image sizes in Settings > Media), and tells it to wrap the list in a div instead of an unordered list so we don't have bullets.

This plugin does not include any styling of the listings so that you can make them look however you want. In order to get the image floating to the left, add this to your theme's style.css:

.display-posts-listing .listing-item {
	clear: both;

.display-posts-listing img {
	float: left;
	margin: 0 10px 10px 0;

Customizing the Excerpt

If you use [display-posts include_excerpt="true"] it will use the standard excerpt settings as defined by WordPress and your theme. Typically this means 55 word length and [...] at the end if the excerpt was shortened, but your theme can change these.

Display Posts Shortcode lets you customize these without writing any code. If you use any of the following parameters, we'll build a custom excerpt based on your settings.

  • excerpt_length - Set the length of the excerpt, in words. Default is 55
  • excerpt_more - Add some type of "more" text to the end of all excerpts. Default is empty
  • excerpt_more_link - Make the "more" text link to your post. Default is false (no link)


[display-posts include_excerpt="true" excerpt_length="20" excerpt_more="Read More" excerpt_more_link="true"]

Date Queries

There are 8 parameters for managing date queries:

  • date — Serves as a shortcut to setting the 'year', 'month', and 'day' arguments for a given date query struct on the second-level. It accepts either a strictly-formatted 'YYYY-MM-DD' date string or a relative-formatted date string, such as 'Sunday, September 7'. The relative-formatted string is intended as a fallback for the easier-to-sanitize 'YYYY-MM-DD' formatted string and could prove fickle when supplied with too little information.

  • date_column — The first of two top-level arguments, this serves as the "global" column to query for all date queries in the date query arrays on the second-level. This defaults to 'post_date'.

  • date_compare — The second of two top-level arguments, this serves as the "global" comparison operator for all date queries in the date query arrays on the second-level. This defaults to '='.

  • date_query_before — Sets the 'before' argument for a date query on the second level. It accepts either a strictly-formatted date, 'YYYY-MM-DD', or as a fallback, a relative-formatted date string (using the same logic as the date attribute).

  • date_query_after — Sets the 'after' argument for a date query on the second level. Like the date_query_before attribute, It accepts either a a strictly-formatted date, 'YYYY-MM-DD', or as a fallback, a relative-formatted date string (using the same logic as the date attribute.

  • date_query_column — Sets the column to query by for the second-level date query. If not set, falls back to the value of date_column.

  • date_query_compare — Sets the comparison operator for the second-level date query. If not set, falls back to the value of date_compare.

  • time — Serves as a shortcut to populating the 'hour', 'minute', and 'second' arguments in the second-level date query. It accepts only a strictly-formatted string in the format of 'HH:MM:SS' or 'HH:MM'. This does NOT have a string falback.

Here are some sample shortcodes: Query for posts published on a specific date:

[display-posts date="2014-09-07"]
[display-posts date="Sunday, September 9, 2014"]

Query for posts published after January 1, 2013:

[display-posts date_query_after="2013-01-01"]
[display-posts date_query_after="January 1, 2013"]

Query for posts published BEFORE today:

[display-posts date_query_before="Today"]

Query for posts modified yesterday:

[display-posts date="Yesterday" date_query_column="post_modified"]

More information in the Date Query pull request

Multiple Taxonomy Queries

While most people will only ever need a single taxonomy query, this plugin supports an infinite number of taxonomy queries. Let's say you wanted to get all posts in category "featured" and also tagged "homepage". We'll use a shortcode that looks like this:

[display-posts taxonomy="category" tax_term="featured" taxonomy_2="post_tag" tax_2_term="homepage"]

You can string as many of those as you like, just start the count at 2. In the field listing below, replace (count) with an actual number.

Here's the available fields:

Which taxonomy to query
Default: empty

Which terms to include (if more than one, separate with commas)
Default: empty

How to query the terms (IN, NOT IN, or AND)
Default: IN

Describe the relationship between the multiple taxonomy queries (should the results match all the queries or just one of them). Available options: AND and OR
Default: AND


A common question I receive is how to load the next page of results, or paginate the query. This plugin does not support pagination, nor will it in the future.

If you need pagination in your query, you should not be using a shortcode. Use the WordPress core templates like the category archive or tag archive. Or if you must, build a custom page template that overrides the main WordPress query. Users

This plugin is now available to all users of There's no installation necessary, just drop the shortcode in your page's content area. Unfortunately you won't be to use any of the filters listed in Further Customization since this requires customizing your theme, which isn't allowed on

Known Plugin Conflicts

These are plugins known to cause issues with Display Posts Shortcode. If you are having problems and have one of these installed, I recommend you disable it:

  • Easy Custom Auto Excerpt
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.