Related Posts by Taxonomy

Quickly increase your readers’ engagement by adding related posts in the sidebar or after post content with a widget or shortcode.

Posts with the most terms in common will display at the top!

This plugin is capable of finding related posts in multiple taxonomies and post types. Include or exclude terms from the search for related posts. Change the look and feel by using your own templates in your (child) theme.

Plugin features:

  • Widget and Shortcode
  • Post thumbnails, links, excerpts or full posts.
  • Small Footprint. Doesn’t slow down your site!
  • Search for related posts in single or multiple taxonomies and post types.
  • Exclude or include terms and posts.
  • Limit the search of related posts by date or number.
  • Limit the search of related posts by post meta.
  • Automatic display of related posts after the post content.
  • Use your own Html templates for display of the related posts.
  • Use the WordPress REST API to get related posts. (opt-in feature)
  • Use a persistent cache to get the related posts. (opt-in feature)
  • Use plugin functions in your theme templates to display related posts yourself.
  • Optimize the query for related posts
  • Use Filters to change the default behavior of the plugin.
  • Highly Adjustable!
  • Follows WordPress coding standards and plugin best practices.

Download the plugin from the WordPress plugin repository: Related Posts by Taxonomy Plugin

For support visit the WordPress forums.

Visit the github repository for the development version.

The plugin documentation

Use the links below to navigate to a specific section in the documentation:

Note: It’s recommended you create a child theme whenever the documentation provides a way to modify the plugin by adding code to theme template files.

How to install the plugin

  1. Unzip the folder.
  2. Upload the related-posts-by-taxonomy folder to your /wp-content/plugins directory.
  3. Activate Related Posts by Taxonomy.
  4. That’s it, now you are ready to use the widget and shortcode.


The widget allows you to display related posts in the widgetized areas of your theme. Usually you can add widgets in the sidebar or footer, however these widget-ready areas can also be in the header, below content, and basically any other area in your theme. You can find the widget by going to the Appearance » Widgets admin page.

The display settings

You can choose from four different display formats:

  1. links: display a list of related post links
  2. posts: display a list of full posts
  3. excerpts: display a list of excerpts
  4. thumbnails: display a list of post thumbnails (version 0.2)

To override (edit) the templates used to display these formats see: Templates

For more information about the post ID and the widget outside the loop see Usage outside the loop.

To filter the widget see the widget filters.


A shortcode is a WordPress-specific code to publish dynamic content using macros, without the need for programming skills. When a shortcode is inserted in a WordPress post or page editor, it is replaced with some other content.

Basic usage


This in your post content will be replaced with a list of related posts.

Shortcodes can also be used with additional attributes as the following example shows:

[related_posts_by_tax format="thumbnails" image_size="medium"]

This will be replaced by medium sized related thumbnails.

Note: To add the related posts automatically after the post content it’s recommended you use this method instead of the shortcode.


All default attribute values can be filtered in your (child) theme’s functions.php file. This allows you to set your own defaults and more. See this Filter.

(int) Display related posts for a specific post ID. There is no default.
[related_posts_by_tax post_id="23"]
(string) Taxonomy name or a comma-separated list of taxonomy names. Default is empty string (Use all taxonomies to find related posts).
[related_posts_by_tax taxonomies="category,post_tag"]
(string) Post type name or a comma-separated list of post type names to search related posts in. Default none. The post type of the current post is used to get related posts for. If no post type is found it defaults to the ‘post’ post type.
[related_posts_by_tax post_types="post,movie"]
(int) How many related posts to display. To display all related posts use -1. Default is 5.
[related_posts_by_tax posts_per_page="10"]
(string) This affects what fields are returned by the related posts query. If you set it to ‘ids’ the query is smaller and faster than the default. Please read the ID query documentation before setting it to ‘ids’. Default empty string (return all fields)
[related_posts_by_tax fields="ids"]
(string) Start searching for related posts from latest post date, oldest post date or randomly.

  • ‘DESC’ – from latest post date (show posts with most common terms first)(default).
  • ‘ASC’ – from oldest post date (show posts with most common terms first).
  • ‘RAND’ – random (show posts with terms in common randomly).
[related_posts_by_tax order="ASC"]
(string) Order by post date or by date modified.

  • ‘post_date’ – order by date (and show posts with most common terms first)(default).
  • ‘post_modified’ – order by last modified date (and show posts with most common terms first).
[related_posts_by_tax orderby="post_modified"]
(string) Text or Html to place before the shortcode.
Default is <div class="rpbt_shortcode">.
(string) Text or Html to place after the shortcode.
Default is </div>.
[related_posts_by_tax before_shortcode='<div>' after_shortcode='</div>' ]
(string) The title displayed above the related posts. Default is ‘Related Posts’. The title is removed if left empty.
[related_posts_by_tax title="My Related Posts"]
(string) Text or Html to place before the title. Default is <h3>.
(string) Text or Html to place after the title. The default is </h3>.
[related_posts_by_tax before_title='<h3 class="rpbt_title">' after_title="</h3>"]
(boolean) Show the post date after post titles. Default is ‘false’.
[related_posts_by_tax show_date="true"]
(string) Search for related posts by term IDs. Use a comma separated list of term IDs. The posts are ordered by most terms in common. Default is an empty string (Query for related posts with the current post terms).
[related_posts_by_tax include_terms="20,23,14"]
(boolean) Include parent terms in the query for related posts. Default false
[related_posts_by_tax include_parents="true"]
(boolean) Include child terms in the query for related posts. Default false
[related_posts_by_tax include_children="true"]
(string) Exclude a comma separated list of term IDs. Default is an empty string (don’t exclude terms).
[related_posts_by_tax exclude_terms="20,23,14"]

If you get unexpected results see the plugin’s logic for excluding terms.

(string) Exclude a comma separated list of post IDs. Default is an empty string (don’t exclude posts).
[related_posts_by_tax exclude_posts="83,102,44"]
(string) Display related posts as links, full posts, excerpts or post thumbnails.

  • ‘links’ (default):
    • display a list of related post links.
    • template used for display: related-posts-links.php.
  • ‘posts’:
    • display post title and full post.
    • template used for display: related-posts-posts.php.
  • ‘excerpts’:
    • display post title and excerpt.
    • template used for display: related-posts-excerpts.php.
  • ‘thumbnails’:
    • display post thumbnails and post title as caption (same as the gallery shortcode).
    • template used for display: related-posts-thumbnails.php.

To override (edit) the templates used for display see Templates

[related_posts_by_tax format="thumbnails"]
(string) Image size used for the format thumbnails (see above). Choose from the default image sizes thumbnail, medium, large, post-thumbnail and the image sizes set by the current theme. Default is ‘thumbnail’
[related_posts_by_tax image_size="medium" format="thumbnails"]
(string) Set the number of image columns for the format thumbnails (see above). Default is 3
[related_posts_by_tax columns="2" format="thumbnails"]
(string) Caption text for the post thumbnail. Choose from post_title, post_excerpt attachment_caption, attachment_alt, or a custom string. Default is ‘post_title’
[related_posts_by_tax caption="post_excerpt" format="thumbnails"]
[related_posts_by_tax link_caption="true" format="thumbnails"]
(string) Limit the search for related posts to the latest published posts only. Default is ‘-1’ (search in all posts). Example: search for related posts in the last 100 posts.
[related_posts_by_tax limit_posts="100"]
(string) Limit the search for related posts to posts published in the past year(s). Default is an empty string (no limit). Example: search only in posts published within the last year.
[related_posts_by_tax limit_year="1"]
(string) Limit the search for related posts to posts published in the past month(s). Default is an empty string (no limit). Example: search only in posts published within the last 6 months.
[related_posts_by_tax limit_month="6"]
(string) Post meta key. See WP_Query for more information. Default empty string (no meta query)
[related_posts_by_tax meta_key="my_meta_key"]
(string) Post meta value. Use a comma separated string for array values. See WP_Query for more information. Default empty string (no meta query)
[related_posts_by_tax meta_value="my_meta_value"]
(string) Operator to test the `meta_value`. Possible values are ‘=’, ‘!=’, ‘>’, ‘>=’, ‘<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP' or 'RLIKE'. See WP_Query for more information. Default value is '='.
[related_posts_by_tax meta_value="my_meta_value" meta_compare="NOT LIKE"]
(string) Post meta type. Possible values are ‘NUMERIC’, ‘BINARY’, ‘CHAR’, ‘DATE’, ‘DATETIME’, ‘DECIMAL’, ‘SIGNED’, ‘TIME’, ‘UNSIGNED’. See WP_Query for more information. Default value is ‘CHAR’.
[related_posts_by_tax meta_key="my_meta_key" meta_value="2" meta_type="NUMERIC"]
(boolean)(2.3.2) Exclude private posts in the related posts results even if the current user has the capability to see the private posts. Default is ‘false’ (include private posts). Example: exclude private posts.
[related_posts_by_tax public_only="true"]
(boolean)(2.3.2) Include the current post in the related posts results. Default is ‘false’ (exclude current post). Example: to include the current post.
[related_posts_by_tax include_self="true"]
(string). Add a class to the related post items. Default is an empty string (don’t add a class). Example: add the “my-class” class.
[related_posts_by_tax post_class="my-class"]

Adding Related Posts After the Post Content

Add related posts automatically after the post content by using a code snippet in your (child) theme’s functions.php file

Example with four related posts after the content on all single post pages.

Note: See below this code snippet how you can change it to suit your needs.

add_filter( 'the_content', 'add_related_posts_after_post_content' );
function add_related_posts_after_post_content( $content ) {

	//check if it's a single post page.
	if ( is_single() ) {

		// check if we're inside the main loop
		if ( in_the_loop() && is_main_query() ) {

			// add your own attributes here (between the brackets [ ... ])
			$shortcode = '[related_posts_by_tax posts_per_page="4"]';

			// add the shortcode after the content
			$content = $content . $shortcode;

	return $content;

Adding your own attributes to the code above
Add the attributes to the code snippet above as you would with the shortcode in the post editor. Let’s say you want to have the code snippet above show six medium sized related thumbnails. All you would have to do is change this:

$shortcode = '[related_posts_by_tax posts_per_page="4"]';

to this:

$shortcode = '[related_posts_by_tax posts_per_page="6" format="thumbnails" image_size="medium"]';

See the shortcode attributes you can add to the $shortcode variable.

Widget usage outside the loop

If the widget is used outside the loop (like in a sidebar) and no post ID is provided in the widget’s settings it gets the first post ID for that page request (e.g. on a category archive page it will get the post ID from the first post of that category archive page).

Custom queries with WP_Query()

To let the widget get the first post ID outside the loop on pages that query the main loop with new WP_Query you have to make some alterations after the query:

<?php // example query
$the_query = new WP_Query('cat=3');

// add this right after the query
// use the query object ($the_query) to check if posts are found
$the_query_id = ( isset( $the_query->post->ID ) ) ? $the_query->post->ID : 0;
set_query_var( 'km_rpbt_related_post_id', $the_query_id );

74 thoughts on “Related Posts by Taxonomy

  1. This plugin is awesome, i tried a bunch of plugins without succeed, but this one is easy to use with great parameters, thank you so much

  2. Hi Keesie,

    great Plugin. I got one issue with it:

    i use photolux as theme and your plugin as widget on singlepage.
    settings are “thumbnail” and here is a problem. the thumbnail is set as image but the imagelink is to the page it self. photolux trys to show the thumbnail as image with lightbox and do not forward to the post.

    any suggestions?

    regards torsten

  3. A question. I would like to use the shortcode alone to place the posts (actually just the thumbnails but I got that part) related to a page on the page. But because it grabs from taxonomy the page doesn’t have a “category” or a “tag” and so I’m lost. Hints? Is this outside the bounds of what this plugin can do? Apologies if this is a basic question. Thank you.

  4. Hello!

    I really liked Your plug-in “Related Post by Taxonomy”
    But I ran into a problem: all miniatures of posts are built in one column. Unable to set, for example 4 or 8 columns. Or display of 5-6 thumbnails on each row.
    Have you encountered this problem? And whether it is possible to solve it somehow?

    Thank you very much, for your attention.
    Sincerely, Tony.

  5. Hi! Please help me, it is work in default taxonomy post, but not work not display in new my taxonomy portfolio, I used it code for register_taxonomy and register_post_type

    [[code removed]]

    and in file single-portolio.php used it code

    but not work, please help me, dear friend (

  6. I try this plugin with the code below to show related post after first paragraph, it works fine in single article but when trying to home page, there is only white page! I don’t know what happen?

    Does this plugin conflict with other plugins?

    [[code removed]]

    1. Hi vuongdaovan
      What happens if you put this:

      $related_posts= do_shortcode('[related_posts_by_tax title=""]');

      inside the is_single() conditional:

      if ( is_single() ) {
      $related_posts= do_shortcode('[related_posts_by_tax title=""]');
      return count_paragraph( $related_posts, 1, $content );
  7. Dear,
    Let me introduce myself. My name is Borisa Djuraskovic. I am associated with Web Hosting Hub community team.

    I found your Related Posts by Taxonomy plugin at very interesting. I would like to translate it to my native Serbo-Croatian language and help people from my community find your plugin useful too.
    Do you mind if I do so?
    Please let me know.

    Borisa Djuraskovic

    1. Hi Borisa Djuraskovic

      I would very much appreciate it 🙂
      You can contact me here.

      If you’re not familiar with translating a plugin check out this tutorial. I have no problem if you’re using other tools to do the translation or want to send me the translation strings in a text file. But I’m guessing you already know how to do this.

      If you want I can add a link to your website next to the translation in the WordPress repository plugin page. Let me know in the contact form what the link should be.

      Thanks 🙂

  8. What a fantastic plugin, so clean and light- thank you!

    I’m using it in the functions.php file of my child theme but the “Related Posts” text is unformatted. I’ve noticed that there is no css class applied to this heading. Is there a future-proof way to style the “Related Posts” text and the actual related posts wrapper itself?

    Thank you!

    1. Hi Tee

      See the examples for this filter how you can change the shortcode title.

      The widget title before and after title is set by your theme. If you need to add to or change the html of the related posts you can do so by using your own templates:

      Could you please open a topic in the WordPress forums if you have any more questions.

      1. I am working locally with wampserver. In fact this displays me the name of my Custom Post Types instead of the title.

  9. Hi Keesie,

    Fantastic plugin! I’m running a movie review website and this widget is really useful.
    However, I’m using two different images per post: the featured image and a custom field with an image as object (that is the DVD cover image). I’d like to use the secondary image file, instead of the automatically generated thumbnail that is based on the featured image, for the thumbnail view.

    Normally, I would use “$image = get_field(‘dvd_cover’);” and “$url = $image[‘url’];” to get the image vars, but how can I implement this in your plugin?

    Many thanks!

      1. Thanks for your quick reply. The difference with your example is that my posts do have thumbnails, but I want to use an image file that is uploaded in a custom field. I assume I need to use “wp_get_attachment_image()” for this, but I don’t know how to handle the parameters (I’m just getting into WordPress). The only thing I know is that the image is an object which is placed in the field ‘dvd_cover’.
        Are you able to help me with this?

  10. Thanks, your example works fine! The only thing is that it shows the attachment of the current post, not of the related post that it points to.
    Fixed it by adding $related it: get_field( ‘dvd_cover’, $related);

    Thank you for your help!

  11. Fantastic plugin! Doesn’t slow it down and it is easily styled. I do have one question though and I don’t really venture into php or java – is it possible to feature outside website posts as a “related” post – which would be fantastic for sites that feature guest posts from other blogs (returning the favor for being allowed to post such content is to highlight their other work etc).

  12. Great plugin – although I’m having one small issue.

    I’d like to display related posts based on a single tag – but this will be output onto a page using the shortcode.

    I’ve installed a plugin to add matching tags to pages, but setting [related_posts_by_tax format=”thumbnails” image_size=”medium” posts_per_page=”3″ order=”RAND” taxonomies=”post_tag”] and it just comes up blank.

    Is there a way I can specify which tag I want it to search for to pull the related content?

    Any ideas?

    Thanks in advance!

  13. Hi, is this possible to show on the widget list – the title of the active post? Currently, when I click one of the titles it goes to the chosen title and hides the chosen title on the widget list. E.g.:
    I would rather bold the chosen title than hide it. Is it possible to achieve this?

    Best for you

  14. Hi. I have a customized taxonomy called “stores”. These stores have categories (tec, books, smarpthones, general retail etc.). In the single store frontend I would like to show the related “stores” belonging to the same category. Some shops may belong to more than 1 category. How could your plugin help me, it is possible to make this modification?

  15. Hey, thanks for making this awesome plugin and making it available. My question is – I am filtering by tag but would like to show the post category under the thumbnail. Can that be done with a shortcode?

  16. I just wanted to thank you greatly for making this plugin, and making it so easy to customize with a shortcode. This solved all my trouble 🙂

  17. Hello Keesie

    I’ve looked the past hour, but I can’t seem to find the widget setting on my WordPress? I specifically want to automatically add related posts with thumbnails on each post.

    However, after looking at your screenshots and reading the FAQ above, i can’t seem to find this widget setting?

    Can you kindly help? Thank you!

  18. Hi

    I love this plugin, thanks anymore

    But how title “related post” instead of heading 3?
    I want a regular format with bold

    I use it after paragraph 3

    please i need this answer

  19. How can I use this widget to the bottom of all the articles that were previously posted. I mean where where should I drop the shortcode so all of the posts and pages display related articles? How can I remove “Related posts” term that is displayed on the top?

  20. I am using shortcode on custom post type, it gets the post permalinks but its not getting the thumbnail, may be I am using external image url for featured image, just guessing (will it only work for featured image that are uploaded in media library?)

    [related_posts_by_tax post_types=”vaping_deals” posts_per_page=”12″ format=”thumbnails” image_size=”medium”]

  21. wonderful! Thank you very much.
    I have a question:

    – If we use Random, do the plugin called Ajax or execution? (We are using Siteground host, so we need to minimize the execution on the server).

  22. Hey Kessie, love your plugin! I have one little question: The text of my blog post headings seems to be “stuck” directly to the thumbnail. Is there a way to add some padding between the two? Thanks a lot for your help!

  23. The plugin is great and really customizable! A quick note for your documentation: When displaying as thumbnails, if you set columns=”0″ then the display will become responsive on mobile devices. Otherwise, the default 3 columns causes everything to be crammed together. Specifying columns=”0″ allows everything to nicely stack as an inline-block.

    1. That’s totally not true. When I specified columns=”0″, I got thumbnails one under the other on desktop, instead of in 3 columns.

  24. Hello, is there any way to change the font or colour of the text? This plugin works great but it shows the text in red on my site which does not go with the brand. Any way I can change it?

  25. How to display related posts from certain ‘tag’ or ‘category’ on specific post/page? I want to display custom related posts that match the ‘tag’ of the new post!

  26. First of all, Man GREAT JOB !
    Thank you a lot for the time spent on it.

    Now the why: 45px image’s, who is the one using that in 2020? Is 6K monitor time. 😀

    More seriously, any simple way to use bigger than 45×45 for the 150×150 thumbnails format ?

    By advance, thanks.


  27. It’s great this plugin, but is not responsive, dont work really well in mobile version… can you check please? because is a nice, easy and simple plugin. Well Done!

    1. Hi, I use this amazing plugin as well. From my experience I can tell you that Keesie Meijer definitely meant for it to be customized further by the site developer/owner to best match with the theme being used.

      If you go through the awesomely written documentation here you’ll find it’s quite easy to make it look perfect on all screen sizes.

      I’m also willing to help if you want.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s