List Category Posts allows you to list posts by category in a post/page using the [catlist] shortcode. This shortcode accepts a category name or id, t
Since the documentation on how to use the plugin has passed wordpress.org's character limit, the text was cut. I've since started using a wiki for more comfortable reading and maintaining. Please check it out, suggestions are welcome on GitHub issues!
The plugin can figure out the category from which you want to list posts in several ways. You should use only one of these methods since these are all mutually exclusive, weird results are expected when using more than one:
When using List Category Posts whithout a category id, name or slug, it will post the latest posts from every category.
[catlist id=1+2-3]. Important: When using the and relationship, you should write the categories you want to include first, and then the ones you want to exclude. So
[catlist id=1+2-3]will work, but
child_categories - Exclude/include posts from the child categories. By default they are included. If you have a "Parent Category" and you use:
[catlist name="Parent Category"], you'll see posts from it's child categories as if they were posts from the same category. You can use this parameter to exclude these posts:
[catlist name="Parent Category" child_categories=false].
author_posts - Get posts by author. Use 'user_nicename' (NOT
tags - Tag support, display posts from a certain tag. You can use an "OR" relationship
[catlist tags="nintendo,sega"] or "AND" relationship (posts that belong to all of the listed tags):
taxonomy - You can select posts using custom taxonomies. You need to set the taxonomy and the terms:
[catlist taxonomy='person' terms='bob'].
currenttags - Display posts from the current post's tags (won't
work on pages since they have no tags). Pass it the 'yes' string for it to work:
exclude_tags - Exclude posts from one or more tags:
[catlist tags="videogames" exclude_tags="sega,sony"]
starting_with - Get posts whose title starts with a certain
[catlist starting_with="l"] will list all posts
whose title starts with L. You can use several letters:
monthnum and year - List posts from a certain year or month. You can use these together or independently. Example:
[catlist year=2015] will list posts from the year 2015.
[catlist monthnum=8] will list posts published in August of every year.
[catlist year=2012 monthnum=12] will list posts from December 2012.
date ranges - You can also use date ranges for listing posts. For example "list every post after March 14th, 2005". The parameters are:
after, after_year, after_month, after_day, before, before_year, before_month, before_day. These parameters are used to specify data_query arguments (see: the codex).
If you want to list all the posts before a given date, say
Jun 17th, 2007 you can use these two options:
[catlist before_year=2007 before_month=06 before_day=17]
Or you can use the
before parameter with a strtotime()-compatible string:
The same works for posts after a given date, you can use:
[catlist after_year=2007 after_month=06 after_day=17]
after with a strtotime()-compatible string:
after takes priority over
before takes priority over
search - List posts that match a search term.
[catlist search="The Cake is a lie"]
excludeposts - IDs of posts to exclude from the list. Use 'this' to exclude the current post. Ex:
offset - You can displace or pass over one or more initial posts which would normally be collected by your query through the use of the offset parameter.
post_type - The type of post to show. Available options are: post - Default, page, attachment, any - all post types. You can use several types, example:
[catlist post_type="page,post" numberposts=-1]
post_status - use post status, default value is 'publish'. Valid values:
[catlist post_status="future, publish" excludeposts=this]
show_protected - Show posts protected by password. By default
they are not displayed. Use:
post_parent - Show only the children of the post with this ID. Default: None.
custom fields - To use custom fields, you must specify two values: customfield_name and customfield_value. Using this only show posts that contain a custom field with this name and value. Both parameters must be defined, or neither will work.
conditional_title - Display a custom title before the posts list.
The title is not displayed if the list is empty. Set to the empty string
(default value) to disable.
[catlist conditional_title="Other posts"].
conditional_title_tag - Specify the tag used for the conditional title. Defaults to 'h3'.
conditional_title_class - Specify the class used for the conditional title. Defaults to the empty string (no special class).
orderby - To customize the order. Valid values are:
[catlist name=mycategory orderby=date]
customfield_orderby - You can order the posts by a custom field. For example:
[catlist numberposts=-1 customfield_orderby=Mood order=desc] will list all the posts with a "Mood" custom field. Remember the default order is descending, more on order:
order - How to sort orderby. Valid values are:
[catlist name=mycategory orderby=title order=asc]
numberposts - Number of posts to return. Set to 0 to use the max
number of posts per page. Set to -1 to remove the limit.
[catlist name=mycategory numberposts=10]
You can set the default number of posts globally on the options
page on your Dashboard in Settings / List Category Posts.
no_posts_text - Text to display when no posts are found. If you don't specify it, nothing will get displayed where the posts should be.
date - Display post's date next to the title. Default is 'no',
use date=yes to activate it. You can set a css class and an html
tag to wrap the date in with
date_tag (see HTML
& CSS Customization further below).
date_modified - Display the date a post was last modified next
to the title. You can set a css class and an html tag to wrap the
date in with
HTML & CSS Customization further below).
author - Display the post's author next to the title. Default is
'no', use author=yes to activate it. You can set a css class and an html
tag to wrap the author name in with
author_tag (see HTML
& CSS Customization further below).
When displaying the post author, you can also display a link to the author's page. The following parameter only works if author=yes is present in the shortcode:
dateformat - Format of the date output. The default format is the one you've set on your WordPress settings. Example:
[catlist id=42 dateformat="l F dS, Y"] would display the date as "Monday January 21st, 2013". Check http://codex.wordpress.org/Formatting_Date_and_Time for more options to display date.
excerpt - Display a plain text excerpt of the post. Default is 'no', use
excerpt=full to activate it. If you have a separate excerpt in your post, this text will be used. If you don't have an explicit excerpt in your post, the plugin will generate one from the content, striping its images, shortcodes and HTML tags. If you want to overwrite the post's separate excerpt with an automatically generated one (may be useful to allow HTML tags), use
If you use
excerpt=yes, the separate excerpt or content will be limited to the number of words set by the excerpt_size parameter (55 words by default).
If you use
excerpt=full the plugin will act more like WordPress. If the post has a separate excerpt, it will be used in full. Otherwise if the content has a <!--more--> tag then the excerpt will be the text before this tag, and if there is no <!--more--> tag then the result will be the same as
If you want the automatically generated excerpt to respect your theme's allowed HTML tags, you should use
excerpt_strip=no, otherwise the HTML tags are automatically stripped.
excerpt_size - Set the number of words to display from the excerpt. Default is 55. Eg:
excerpt_strip - Set it to
yes to strip the excerpt's HTML tags. If the excerpt is auto generated by the plugin, the HTML tags will be stripped, and you should use
excerpt_strip=no to see the excerpt with HTML formatting.
title_limit - Set the limit of characters for the title. Ex:
[catlist id=2 title_limit=50] will show only the first 50
characters of the title and add "…" at the end.
content - WARNING: If you want to show the content on your listed posts, you might want to do this from a new Page Template or a Custom Post Type template. Using this parameter is discouraged, you can have memory issues as well as infinite loop situations when you're displaying a post that's using List Category Posts. You have been warned. Usage:
yes - Show the excerpt or full content of the post. If there's a <!--more--> tag in the post, then it will behave just as WordPress does: only show the content previous to the more tag. Default is 'no'. Ex:
full - Show the full content of the post regardless of whether there is a <!--more--> tag in the post. Ex:
catlink - Show the title of the category with a link to the category. Use the catlink_string option to change the link text. Default is 'no'. Ex:
[catlist catlink=yes]. The way it's programmed, it should only display the title for the first category you chose, and include the posts from all of the categories. I thought of this parameter mostly for using several shortcodes on one page or post, so that each group of posts would have the title of that group's category. If you need to display several titles with posts, you should use one [catlist] shortcode for each category you want to display.
category_description Show the category description wrapped in a p tag:
[catlist id=1 category_description='yes']
catname - Show the title of the category (or categories), works exactly as
catlink, but it doesn't add a link to the category.
category_count - Shows the posts count in that category, only works when using the catlink option:
[catlist name=nintendo catlink=yes category_count=yes]
comments - Show comments count for each post. Default is 'no'. Ex:
thumbnail - Show post thumbnail (http://markjaquith.wordpress.com/2009/12/23/new-in-wordpress-2-9-post-thumbnail-images/). Default is 'no'. Ex:
force_thumbnail - If the previous parameter is set to 'yes', and there's no featured image, setting this to 'yes' or 'true' will make the plugin look for the first image in the post and use it as a thumbnail. Ex:
[catlist thumbnail=yes force_thumbnail=yes].
thumbnail_size - Either a string keyword (thumbnail, medium, large or full) or 2 values representing width and height in pixels. Ex:
[catlist thumbnail_size=32,32] or
thumbnail_class - Set a CSS class for the thumbnail.
post_suffix - Pass a String to this parameter to display this
String after every post title.
post_suffix="Hello World"] will create something like:
<ul class="lcp_catlist" id=lcp_instance_0>
<a href="http://127.0.0.1:8080/wordpress/?p=42" title="WordPress">
</a> Hello World </li>
display_id - Set it to yes to show the Post's ID next to the post title:
[catlist id=3 display_id=yes]
class - CSS class for the default UL generated by the plugin.
customfield_display - Display custom field(s). You can specify
many fields to show, separating them with a coma. If you want to
display just the value and not the name of the custom field, use
customfield_display_name and set it to no.
By default, the custom fields will show inside a div with a
<div class="lcp-customfield">. You can customize
this using the customfield_tag and customfield_class parameters to
set a different tag (instead of the div) and a specific class
(instead of lcp-customfield).
customfield_display_glue - Specify the text to appear between two custom
fields if displayed together, defaults to the empty string. Not used if
customfield_display_separately parameter is defined.
customfield_display_separately - Display the custom fields separately.
Each custom field is displayd within its own tag (see
Defaults to 'no', set to 'yes' to enable. Superseeds the
customfield_display_glue parameter when enabled.
customfield_display_name - To use with
Use it to just print the value of the Custom field and not the
[catlist numberposts=-1 customfield_display="Mood" customfield_display_name="no"]
Will print the value of the Custom Field "Mood" but not the text "Mood: [value]".
customfield_display_name_glue - To use with
Use it to specify the text between the name and the value, defaults to
' : '.
template - By default, posts will be listed in an unordered list (ul tag) with the class 'lcp_catlist':
<ul class="lcp_catlist"><li><a href="post1">Post 1</a></li>...
You can use a different class by using the class parameter.
You can create your own template file (Check Template System
further down this document) and pass it as a parameter here. The
parameter is the template name without the extension. For example
mytemplate.php, the value would be
You can also pass these two parameters which yield different results:
div - This will output a div with the
(or one you pass as a parameter with the
class argument). The
posts will be displayed between p tags.
ol - This will output an ordered list with the
css class (or the one you pass as a parameter with the
argument) and each post will be a list item inside the ordered list.
morelink - Include a "more" link to access the category archive for the category. The link is inserted after listing the posts. It receives a string of characters as a parameter which will be used as the text of the link. Example:
[catlist id=38 morelink="Read more"]
posts_morelink - Include a "read more" link after each post. It receives a string of characters as a parameter which will be used as the text of the link. Example:
[catlist id=38 posts_morelink="Read more about this post"]
link_target - Select the
target attribute for links to posts (target=_blank, _self, _parent, _top, *framename*). Example:
[catlink id=3 link_target=_blank] will create:
<a href="http://localhost/wordpress/?p=45" title="Test post" target="_blank">Test post</a>
no_post_titles - If set to
yes, no post titles will be shown. This may make sense together with
link_titles - Option to display titles without links. If set to
false, the post titles won't be linking to the article.
link_dates - Option to wrap dates with a link to the post. Set to
yes to enable, set to
no to disable. Defaults to
The widget is quite simple, and it doesn't implement all of the plugin's functionality. To use a shortcode in a widget add this code to your theme's functions.php file:
Then just add a new text widget to your blog and use the shortcode there as the widget's content.
Requires: 3.3 or higher
Compatible up to: 4.7.1
Last Updated: 2 weeks ago
Active Installs: 100,000+
0 of 19 support threads in the last two months have been marked resolved.
Got something to say? Need help?