How to select which posts to show

Selecting a category

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:

• Using the category id.
  • id - To display posts from a category using the category's id. Ex: [catlist id=24].
• The category name or slug.
  • name - To display posts from a category using the category's name or slug. Ex: [catlist name=mycategory]. It's a better practice to use the category id. That way, if you change your category's name or slug, you won't have to change your List Category Posts shortcodes or they'll break otherwise. It's also generally safer to use the ID than to deal with strings.
• Detecting the current post's category. You can use the categorypage parameter to make it detect the category IDs of the current post, and list posts from that category.
  • categorypage - Set it to:
    • "yes" if you want to list the posts from all the current post's categories with OR relationship. [catlist categorypage="yes"]
    • "all" for AND relationship. [catlist categorypage="all"]
    • "other" to get all categories except current categories (with OR relationship). [catlist categorypage="other"]
  • as an exception from the rule of using only one method, you can use the id parameter together with categorypage to exclude selected categories, see below for more information on excluding categories. Ex. [catlist categorypage=yes id=-3,-4]

When using List Category Posts whithout a category id, name or slug, it will post the latest posts from every category unless you filter out which posts to show with other parameters.

Using more than one category

• Posts from several categories with an AND relationship, posts that belong to all of the listed categories (note this does not show posts from any children of these categories): [catlist id=17+25+2] - [catlist name=sega+nintendo].
• Posts from several categories with an OR relationship, posts that belong to any of the listed categories: [catlist id=17,24,32] - [catlist name=sega,nintendo].
• Exclude a category with the minus sign (-): [catlist id=11,-32,16], [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 [catlist id=1+2-3+4] won't.

Other ways of selecting what posts to show

• 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].

• main_cat_only - When you select a category, e.g. [catlist name="dogs"], the plugin lists all posts with this category assigned even if it is one of many categories of a post. Instead, you might want to select only the posts that have "dogs" as their main category; to do this, add main_cat_only=yes to your shortcode. This is compatible with Yoast's primary category feature, if you are not using Yoast the LCP plugin interprets the first category assigned to a post as its main one.

• author_posts - Get posts by author. Use 'user_nicename' (NOT name). Example: [catlist author_posts="fernando"]. If you want to select posts from several authors, you need to use the author id instead. You can find the id for each author in wp-admin/users.php. It needs to be a comma separated value, example: [catlist author_posts="1,2"]. You can also select posts of the currently logged in user, example: [catlist author_posts="current_user"]

• 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): [catlist tags="nintendo+sega"].

  • The plugin does support multi-word tags like "textual analysis" but you must use a hyphenated tag in the shortcode: [catlist tags="textual-analysis"].

• taxonomy - You can select posts using custom taxonomies. There are three ways of selecting taxonomies:

  • Single taxonomy - you need to set the taxonomy and the terms: [catlist taxonomy='person' terms='bob']. It supports both the "IN" and "AND" logical relationships between each inner taxonomy. For the "AND" relationship, separate terms with a plus sign: [catlist taxonomy='topic' terms='topic1+topic2']. For the "OR" relationship, separate terms with a comma: [catlist taxonomy='topic' terms='topic1,topic2'].
  • Current post's terms - you need to set the taxonomy and specify currentterms=yes: [catlist taxonomy="example" currentterms="yes"]. OR is the default relationship, use currentterms="all" for the AND relationship.
  • Multiple taxonomies - you can use multiple taxonomy terms in one shortcode like this:
    • OR – taxonomies_or="tax1:{term1_1,term1_2};tax2:{term2_1,term2_2,term2_3}"
    • AND – taxonomies_and="tax1:{term1_1,term1_2};tax2:{term2_1,term2_2,term2_3}"

• 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: [catlist currenttags="yes"]. OR is the default relationship, use currenttags="all" for the AND relationship.

• 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 letter. Example: [catlist starting_with="l"] will list all posts whose title starts with L. You can use several letters: [catlist starting_with="m,o,t"].

• 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). Since you can use strtotime()-compatible strings, you can build dynamic lists such as "posts from the last 30 days" with [catlist after='-30 days']. You can also use the 'today' keyword: [catlist before=today], the plugin wil l get today's date dynamically and display only old posts. More examples:

  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:
  [catlist before='2007/06/17']

  The same works for posts after a given date, you can use:
  [catlist after_year=2007 after_month=06 after_day=17]
  Or just after with a strtotime()-compatible string:
  [catlist after='2007/06/17']

  after takes priority over after_year, after_month, and after_day.
  before takes priority over before_year, before_month, and before_day.

• search - List posts that match a search term. [catlist search="The Cake is a lie"] Prepending a term with a hyphen will exclude posts matching that term. [catlist search="-dog cat"] will list posts that match 'cat' but not 'dog'.

• excludeposts - IDs of posts to exclude from the list. Use 'this' to exclude the current post. Ex: [catlist excludeposts=this,12,52,37]

• includeposts - IDs of posts to include in the list. Ex: `[catlist includeposts="2,97"]

• ignore_sticky_posts - if set to yes the plugin ignores all sticky posts, they will still be displayed as regular posts in normal order if they match your filtering options, though. For example, assume we have posts A, B, C, D, E, if post D is sticky, by default WordPress displays D, A, B, C, D, E; with [catlist ignore_sticky_posts=yes] you get A, B, C, D, E.

• cat_sticky_posts - set to 'yes' to make sticky posts 'stick' when filtering by category. By default, when using name or cat shortcode parameters, sticky posts that match selected categories are not put at the beginning of the list. This is how all regular WP queries work, not just this plugin, but if you use cat_sticky_posts=yes the plugin prepends matching sticky posts like in a default loop.

• 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:

  • publish - a published post or page.
  • pending - post is pending review.
  • draft - a post in draft status.
  • auto-draft - a newly created post, with no content.
  • future - a post to publish in the future.
  • private - not visible to users who are not logged in.
  • inherit - a revision. see get_children.
  • trash - post is in trashbin (available with Version 2.9).
  • any - retrieves any status except those from post types with 'exclude_from_search' set to true. You can use several post statuses. Example: [catlist post_status="future, publish" excludeposts=this]

• show_protected - Show posts protected by password. By default they are not displayed. Use: [catlist show_protected=yes]

• 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. customfield_name defines the name of the field, and you should choose the values for which you want posts to display. Using this only show posts that contain a custom field with this name and value. Both parameters must be defined, or neither will work. Eg: [catlist customfield_name="color" customfield_value="green"] will display posts with the value green set on the custom field color. This parameter can be used together with customfield_orderby, see "More parameters you can use" for more information.

• customfield_compare - Allows for more advanced filtering by custom fields. Can be used together with customfield_orderby, customfield_name and customfield_value. The accepted syntax is customfield_compare=name,compare,value,type where:

  • name (required) is the custom field's name
  • compare (required) is one of: equals, not_equals, lessthan, lessthanequal, greaterthan, greaterthanequal, exists, not_exists
  • value (optional) is the value to check against, it should not be specified when exists or not_exists comparisons are used
  • type (optional) is one of NUMERIC, BINARY, CHAR, DATE, DATETIME, DECIMAL, SIGNED, TIME, UNSIGNED. This determines the data type used while comparing values, see MySQL docs for more information. Defaults to CHAR which is fine for most cases but you might want to use NUMERIC when comparing numbers.
  • multiple queries are allowed using ; as delimiter, e.g. [catlist customfield_compare=name,compare,value,type;name2,compare2,value2,type2]. AND relation applies.
  • examples
    • [catlist customfield_compare=myfield,not_equals,Mary] - select all posts that have custom field myfield and its value is not Mary
    • [catlist customfield_compare=myfield,exists] - select all posts that have the myfield custom field
    • [catlist customfield_compare=myfield,lessthan,100,NUMERIC] - select all posts that have custom field myfield and its value (interpreted as a number) is less than 100
    • [catlist customfield_compare=myfield,lessthan,100,NUMERIC;mydate,greaterthanequal,2020-01-01,DATE] - select all posts that have custom field myfield and its value (interpreted as a number) is less than 100 and have custom field mydate and its value (interpreted as a date) is greater than or equal to 2020-01-01
  • For advanced users: you can use regular expressions in value if you use REGEXP as compare but the pattern cannot contain [, ], ,, ; nor other shortcode-forbidden characters.