1. Code
  2. Plugins

Create a Shortcode to List Posts With Multiple Parameters


On many of the client sites I build, I find there are times when I need to include a post listing on a page. I'm not talking about archive pages here, but adding a custom listing to an existing static page.

For example, I might want to list some posts on the 'About' page, or the site may require an in-depth page for a topic, with a list of posts and custom post types related to that topic.

One way to do this is by creating a custom page template to include the current page content plus the results of a second custom query, but if you want more flexibility over how you list posts, or just want to do it a few times, a shortcode will be a simpler solution.

In this tutorial, I'll show you how to create a simple shortcode to list all posts of a custom post type, and then I'll expand on that to create a shortcode with various parameters that users can specify to list posts however they want.

What You Need to Complete This Tutorial

You will need the following resources:

  • A development installation of WordPress
  • Access to your plugins folder so you can create and upload the shortcode plugin

You'll find all of the code to create this plugin in the code download.

Getting Started: Creating the Content

Before setting up the shortcode, you'll need to register a custom post type and two custom taxonomies, which we'll be using to test the shortcode.

The code to do this is contained in the plugin I've written for the shortcode, though on a live project, I'd recommend separating this out from the shortcode plugin itself.

Create a new file in your plugins folder and call it post-listing-shortcode.php.

Add the code below to the file.

Note: Creating the custom post types and taxonomies isn't central to the learning from this tutorial. If you want, you can copy this code from the download file and skip this stage.

This tells WordPress about the plugin and registers the custom post type 'clothes' and the two taxonomies, 'color' and 'fabric'.

Save this plugin and activate it via the Plugins page in WordPress.

Now you have your custom post type and taxonomies in place, create some posts using them. In the screenshot below you can see the content I've created:


Creating a Simple Listing Shortcode

If you only want to list content in one way using your shortcode, you can create a very simple shortcode which doesn't use parameters.

Open your plugin file again and add the following:

This creates a simple shortcode, using WP_Query to run a custom query on your content and output the results in a list. When I type [list-posts-basic] into a page the results are as shown in this screenshot:


Adding Some Parameters to Modify the Query

The shortcode will be much more useful if users can add their own parameters, choosing for example:

  • How many posts to list
  • What post type to query
  • Categories to include
  • Fabrics and colors to include
  • Ordering parameters

To add this to the shortcode, you make use of the shortcode_atts() function, which allows you to specify some default attributes which users can override.

Once again in your plugin file and below the code for the first shortcode, add the following:

Note: Using ob_start() and ob_get_clean() ensures that the loop is output in the place in your page or post that you've added the shortcode. If you don't add these, the list will be displayed at the top of the content.

By default this lists all posts in descending order of date, so if you type [list-posts] into a page or post, the result is as in this screenshot:


However, if you add some parameters things get more interesting. For example, to list all clothes which come in the color black, I type [list-posts type="clothes" color="black" orderby="name" order="ASC"]:


Or to list all clothes in the 'smart' category I type [list-posts type="clothes" category="smart" orderby="name" order="ASC"]:


If you need to you can specify more attributes which users can work with, but you have to include all of the available ones in your plugin, in the extract( shortcode_atts)) function.

You don't have to specify a default for all of them - for example I've left the category and taxonomy parameters empty in the example. The parameters you can define are any of those which can be specified for WP_Query - for a full list, see its Codex page.


Being able to insert a post listing into a page or post can be very useful. It saves you having to modify your template files or write a custom page template.

The shortcode you've learned how to create in this plugin could be used in many ways, and of course you could easily change what's output by the shortcode - my example outputs a bulleted list with post titles enclosed in a link to their page, but you could replace the code inside the loop with the template tags to display the content, featured images, or anything else.


Some useful resources on the topics covered above:

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.