Posts Table Pro – Documentation

Everything you need to know about creating the perfect posts table. It supports posts, custom posts, products and more.

Posts Table Pro provides an easy way to list all of your website content in a searchable and sortable data table. Under the hood it uses the jQuery DataTables plugin to provide the searching and sorting features, as well as pagination and responsive layouts for smaller screens.


Once you have purchased Posts Table Pro you should receive a confirmation email (in addition to your PayPal receipt) which contains your license key and a download link to the plugin. If you don’t receive this email, please get in touch with us.

Once you have downloaded the plugin, go to your WordPress admin, then go to Plugins -> Add New -> Upload Plugin. Click Choose File and select the file you just downloaded. Once uploaded, click Activate.

Entering your license key

Once activated, go to Settings -> Posts Table Pro and enter your license key. This should be contained in the email confirmation that was sent to you after purchase. Click Save Changes to validate and store your license key. If you get an error saving your license key, please try a second time. If the error persists, please view our troubleshooting page.

Updating the plugin

Updates are handled from the WordPress admin, in the same way as other plugins hosted in the repository. When an update is available, you will see a notice in the Plugins menu in the usual way. Click the update link under the plugin to update to the latest version.


To use Posts Table Pro, simply add the shortcode [posts_table] to any page, post, widget or other editable area in the WordPress admin. The default configuration will display your site’s posts, but you can of course customise the table in many different ways using the shortcode options listed below.


Basic usage displaying blog posts:
[posts_table columns="title,content,date,author,tags"]

Displaying pages:
[posts_table columns="title,content" post_type="page"]

Displaying a custom post type:
[posts_table columns="title,content" post_type="product"]

Displaying custom fields:
[posts_table columns="id,title,cf:document_status" post_type="document"]

Displaying taxonomies:
[posts_table columns="title,content,tax:film_category,tax:film_genre" post_type="film"]

Displaying the post excerpt:
[posts_table columns="title,excerpt,author,tags,date"]

Selecting posts in categories “design” or “web”:
[posts_table category="design,web"]

Selecting posts (from custom post type) which have the custom taxonomy term “comedy”:
[posts_table post_type="film" term="film_genre:comedy"]

Selecting posts with a custom field called “show_form” with a value of “yes”:
[posts_table cf="show_form:yes"]

Displaying WooCommerce products, including tags, categories and price (please note that we also have a dedicated WooCommerce plugin which you may wish to use instead of Posts Table Pro – WooCommerce Product Table):
[posts_table columns="title,tax:product_tag,tax:product_cat,cf:_price" post_type="product"]

Displaying featured images (with custom image size):
[posts_table columns="image,title,content" image_size="100x50"]

Choosing custom column headings:
[posts_table post_type=property columns="title:Name,date:Added On,tax:listing_cat:Property Type,cf:property_val:Price (£)"]

Shortcode Options

There are a number of options available with the Posts Table shortcode:


The columns to display in the table. This is the main option in the shortcode and determines which data is displayed.

You can choose from: id, title, content, excerptimage, date, author, categories, tags, status, or any custom field or taxonomy column (see below). You can choose as many columns as you want and in any order. You must separate each column with a comma. It doesn’t matter if there are spaces before or after the comma.

Here’s an example displaying the title, date, post author and excerpt for blog posts:
[posts_table columns="title,date,author,excerpt"]

The id column will display the post ID, which is a unique number used internally by WordPress for each post.
The title column is the main post title.

The content column will show the post content but will be truncated to 15 words. You can modify this length by setting the content_length option.

The excerpt column will show the post excerpt. It will be truncated to 55 words (the WordPress default) but themes and plugins sometimes override this value. To have precise control over the length, you can set the excerpt_length option.

The image column will display the featured image (i.e. the post thumbnail) for the post or page (see image_size option to set a custom size).

The date column will display the date that the post was published. The author column displays the post author’s display name.

The categories and tags columns apply to blog posts only (i.e. post_type="post") and will display the categories or tags for each post (comma-separated if there is more than one).

The status column will show the status of the post (e.g. draft, pending, publish, etc).

Displaying custom fields

Custom fields are a good way to include other types of content in the table. You can use them to store links, buttons, icons, shortcodes from other plugins, etc. You should add the full HTML code or shortcode to the custom field so that the product table can display it correctly. If you’re using shortcodes, you will need to set shortcodes to true.

You can add custom fields to your table using the format cf:<field name>. If you are using Advanced Custom Fields, the field name can be found under the “Field Name” column in the Custom Fields menu.

Here’s an example adding two custom fields – my_field1 and my_field2:
[posts_table columns="title,content,cf:my_field1,cf:my_field2"]

Displaying custom taxonomies

For taxonomies (other than post categories and tags), use the format tax:<taxonomy slug>. So, for example, to display for a custom taxonomy with the slug document_type, you would use:
[posts_table columns="title,content,tax:document_type"].

You can find the taxonomy slug by going to the WordPress admin and finding the main page which lists those taxonomies. For example, WooCommerce product categories are edited under the Products -> Categories menu. On that page, the URL at the top of the screen shows “…edit-tags.php?taxonomy=product_cat….”. The ‘product_cat’ bit after the equals is the taxonomy slug you need to use.

Choosing your own column headings

You can set custom column headings by adding a : (colon) after the column name. You can do this for as many columns as you like. If you don’t set a custom heading, the default one will be used. For example, the default heading for the post title is “Title”, but if you wanted the heading “My Heading” instead, you would use:

[posts_table columns="title:My Heading,date,author,content"]

Here’s a more complex example where we’re displaying a custom post type “property”, and we want to set the title column heading to “Property Description”, the date column to “Added On”, a custom taxonomy to “Type” and a custom field to “Sale Price (£)”:

[posts_table post_type=property columns="title:Property Description, date:Added On, tax:listing_cat:Type, cf:valuation:Sale Price (£)"]

Note in the above example, the taxonomy and custom field columns now have two colons – one to define the taxonomy (or custom field) name, and the other to set the column heading. This is perfectly fine as long as you adhere to the correct syntax shown. For these column types, everything after the second colon will be used as the custom heading.


The sort_by option sets which column should be used for sorting the table by when it is first displayed. Defaults to date which is the date the post or page was published.

You can sort by any column present in the table, or by any of the following keywords (whether or not they are included in your table):

  • id – sort by post ID
  • title – sort by post title
  • menu_order – sort by the ‘order’ option
  • date – sort by the date of the post/page (i.e the publish date)
  • name – sort by post ‘slug’
  • modified – sort by last modified date
  • author – sort by author name
  • comment_count – sort by number of comments
  • type – sort by post type
  • rand – random order

Sort using keyword:  [posts_table columns="title,content" post_type="page" sort_by="menu_order"] 
Sort using column in table:  [posts_table columns="image,title,content,author" sort_by="content"] 


The direction to use for sorting by when the table is first displayed. Can be either asc for ascending order or desc for descending order. Defaults to desc for date-based sorting, and asc for everything else, but you can override using this option.


Controls which blog post categories are displayed in the table. This applies to blog posts only (i.e. where post_type is set to post). If you’re displaying pages or other custom post types, then this option has no effect and you need to use ‘term‘ instead.

You should specify the category slug or category ID – this can be found under the Posts -> Categories menu in the WordPress dashboard. You can also specify multiple categories to display – either separated by commas or by a plus sign (+). If you use commas it means “posts in this Category A or Category B”. If you use a plus, it means “posts in Category A and Category B”.

For example, to display posts which are in the “design” category or in the “print” category, use:
[posts_table category="design,print"]

To display posts which are in the “design” category and in the “print” category, use:
[posts_table category="design+print"]


Applies to blog posts only and selects posts based on their post tags. Use the tag slug or tag ID – you can find this in WordPress under the Posts -> Tags menu.

As with categories, you can use one tag or several tags, and you can use commas or a plus sign to denote how tags should be checked. Using commas means “posts with this tag OR that tag”; using the plus sign (+) means “posts with this tag AND that tag”. You can’t mix and match commas and pluses – it’s one or the other.

Example 1: Display posts with tag “awesome”: [posts_table tag="awesome"]

Example 2: Display posts with tags “cool”, “awesome” or “good”: [posts_table tag="cool,awesome,good"]

Example 3: posts with tags “cool”, “awesome” and “good”: [posts_table tag="cool+awesome+good"]


This option determines which post type (or types) will be displayed in the table. The default is post which will display blog posts. For pages use post_type="page". For attachments you can use post_type="attachment".

For custom post types, you will need to find the ‘slug’ for that post type. The easiest way to do this is to find the post type in the WordPress admin. For example, WooCommerce has a ‘products’ post type. If you go to the ‘Products’ menu in the admin, you will notice in the URL in your browser that it looks something like: “../wp-admin/edit.php?post_type=product”. The “product” bit is the post type you need to use. If you’re using Easy Digital Downloads, use post_type="download".

You can also use a list of post types, separated by commas. For example post_type="page,post", will display all blog posts and pages.


Determines which posts are displayed based on their post status. The default status is publish. The other options are draft, pending, future, private or any. Pending posts are those pending a review. Future posts are those scheduled to be published at a future date. And private posts have their visibility set to Private which means they can only be viewed by the post author or other administrators.

You can also use a list of post statuses separated by commas, for example:
[posts_table columns="title,author,categories" post_status="publish,draft"]


This option applies when you are displaying posts with a custom taxonomy. It allows you to display only those posts which have the specified term or terms. For example, you can use this to display custom posts from a specific category.

Enter this in the format: term="<taxonomy slug>:<term slug>". You can enter one term or multiple terms, and as with categories and tags (see above) you can separate terms using a comma (,) or a plus sign (+) to denote whether the posts have any of the terms specified or all of them.

You need to prefix this option with the slug of the taxonomy followed by a colon. For example, to display WooCommerce products that have the product category “coats”, we would use:
[posts_table columns="title,content" post_type="product" term="product_cat:coats"]

To display posts with multiple terms, you need to add the taxonomy slug before each term. For example, the following shortcode will display WooCommerce products with the category “coats” or “shoes”:

[posts_table columns="title,content" post_type="product" term="product_cat:coats,product_cat:shoes"]

Note (as in this example) that the term doesn’t have to be a column in your posts table.


This option is used to select posts based on a custom field value. You should use the format cf="<field name>:<field value>" when using this option. As with the above options you can enter one custom field to check, or several, and can separate them using a comma or a plus sign (see categories or tags for more details).

For example, if you are displaying a “car” custom post type and wanted to display cars which are either blue OR are Audis, you would use:
[posts_table columns="title,content" post_type="car" cf="color:blue,make:audi"]

However if you wanted to select the blue Audis (i.e. have color = blue AND make = audi) you would use:
[posts_table columns="title,content" post_type="car" cf="color:blue+make:audi"]


The following three options control which posts are displayed based on the date they were published. The “year” option can be set to limit posts to a specific year. E.g. year="2016"


Selects posts from a specific month. You should use a number here between 1 and 12. You can combine this with the year or day options if you want more fine grained control, e.g. year="2015" month="11"


Selects posts from a specific day in the month. You should use a number between 1 and 31, and as above, you can combine this with the year or month options, e.g. month="4" day="25"


Select posts by post author. Use the author ID or a list of IDs.
[posts_table author="1,4"]


The exclude option can be used to exclude posts or pages from your results based on their post ID. You can enter one ID or a list or IDs. For example, if you were displaying a table of your pages, but wanted to exclude the current page (id=23) which the table is displayed on, you would use:

[posts_table columns="title,content" post_type="page" exclude="23"]


The include option can be used to show only specific posts or pages in your table. You can enter one post ID or a list or IDs separated by commas. Note that include and exclude are mutually exclusive – if you set one, the other will be ignored.

Example: you are displaying a table of posts only want to show four specific posts:
[posts_table include="23,45,67,90"]


The exclude_category option is used to exclude entire categories of posts from your table. You can use category IDs or slugs, and it can be one category or a comma-separated list.

Example: [posts_table exclude_category="3,6"]
Example: [posts_table exclude_category="design"]


Controls the maximum number of posts displayed in your table. Defaults to 500 posts. Warning: setting too large a limit could have a performance impact on your server.
[posts_table post_limit="750"]


How many rows to display on each page of results, e.g. rows_per_page="50". The default is 25 rows. Set this to rows_per_page="-1" to show all records in your table.


Controls the style of pagination used for your posts table. Defaults to simple_numbers, which displays numbers for each page plus ‘Previous’ and ‘Next’ buttons. Choose from one of the following:

  • numbers – page numbers only
  • simple – ‘Previous’ and ‘Next’ only
  • simple_numbers – ‘Previous’ and ‘Next’ buttons, plus page numbers
  • full – ‘First’, ‘Previous’, ‘Next’ and ‘Last’ buttons
  • full_numbers – ‘First’, ‘Previous’, ‘Next’ and ‘Last’ buttons, plus page numbers


The filters option allows you to display drop-down lists above your table which allow you to filter (i.e. search) the table by selecting an item from the list.

For example, if you are displaying the categories column, the filter will show all of the categories contained in your table. Selecting a category from the list will filter the table to show posts only from the selected category.

Filters applies to the following columns: categories, tags, author and any custom taxonomy column. One drop-down list will be added for each applicable column in your table.

The filters are displayed above the table by default, but if you have positioned your search box below the table (see display_search_box), then the filters will also appear below the table.

Example: [posts_table filters="true"]


Controls whether to display the “Show <x> entries” drop-down menu, and whether to display it above or below your table. Defaults to top. Choose from one of the following options:

  • top – show page length above the table (top-left)
  • bottom – show it below the table (bottom-left)
  • false – hide the page length drop-down

Controls whether to display the search box for filtering the table by keyword, and where it should appear. Defaults to top. Choose from one of the following options:

  • top – show search box above the table (top-right)
  • bottom – show below the table (bottom-right)
  • false – hide the search box


Controls whether to display the product totals (e.g. “Showing 1 to 10 of 50 entries”), and where to display it. Defaults to bottom. Choose from one of the following:

  • top – show above the table (top-left)
  • bottom – show below the table (bottom-left)
  • false – hide the product totals


Controls whether to display the pagination buttons for scrolling between the results, and where to display them. Defaults to bottom. Choose from one of the following:

  • top – show above the table (top-right)
  • bottom – show below the table (bottom-right)
  • false – hide the pagination buttons.


By default, Posts Table Pro will load all of the data into the table when it is first displayed on screen. If you have more rows than can fit on a single page of results (e.g. you are showing 20 rows per page and you have 30 results) then it will create multiple pages with pagination links at the bottom of the table.

For large numbers of posts, this can cause a hit on performance as all matching posts need to be fetched from the database and then formatted by the plugin. This can result in slower page load times and for very large data sets it may even result in a server or database error when attempting to load the table. If this becomes an issue for you, or you’re worried about performance, we recommend enabling the “lazy load” option. This will load the posts one page at a time rather than all at once. As the user navigates between the pages of results, they will see a “Processing” message displayed (briefly) while the next posts are loaded from the database.

Please note: enabling this option means that all post fetching, searching, and sorting is handled by the server rather than in the browser. Due to limitations in WordPress, the search & filtering features become limited to the title and content columns only, and the ‘search_on_click’ feature is disabled. We hope to provide a fix for this in future.

[posts_table lazy_load="true"]


Posts Table Pro will automatically calculate column widths, but you can override this using the widths option. You need to enter a value for each column in your table – either a percentage, a pixel amount or the keyword “auto” to have the plugin calculate the width automatically.

So for example, if you have 3 columns in your table: title, content and date. And you want to set the width of the title column to 20%, the content column to 50% and the date column to 30%, you would use: [posts_table columns="title,content,date" widths="20,50,30"].

If you wanted to set the width of the first column to 50px, and the other two to be automatically sized you would use:
[posts_table columns="title,content,date" widths="50px,auto,auto"]


By default, Posts Table Pro will automatically calculate column widths to best fit your content in the space available. Set this option to false to disable this feature.
[posts_table auto_width="false"]


This option sets length of content column, if used in your table. Enter the number of words, e.g. content_length="20". The default is 15 words. Set content_length="-1" to show the whole post/page content.


This option sets length of excerpt column, if used in your table. Enter the number of words, e.g. excerpt_length="20". The WordPress default excerpt length is 55 words.


The shortcodes option allows your table to display content generated by any shortcodes used on your site. For example, WordPress provides several built-in shortcodes for displaying audio files, videos, media playlists and image galleries. Enabling this option allows these media files to be displayed in your table.

By default, shortcodes is set to false which will remove all shortcodes from your table. This is done for two reasons: processing shortcode content can take a significant amount of time – especially for large tables – so enabling them can have a performance impact on your site. Secondly, shortcodes often add HTML to the content which makes it difficult to limit content to a set number of words (see content_length and excerpt_length). For this reason, if you enable shortcodes, the full content is always displayed and the content_length option is ignored.

Example: [posts_table columns="image,title,content" shortcodes="true"]


Controls the size of the image column if you are using this in your table. Defaults to thumbnail. You can use any standard image size (thumbnail, medium, large or full), or one or two numbers to denote the exact width and height for the image.

For example, to use the medium image size:
[posts_table columns="image,title,content" image_size="medium"]

For a square image 50 by 50 pixels:
[posts_table columns="image,title,content" image_size="50"]

For an image 50 pixels wide by 40 pixels high:
[posts_table columns="image,title,content" image_size="50x40"]


The date format to use when displaying the date column in your table. If you don’t set this option, the default format in your WordPress settings will be used (see Date Format under the Settings -> General menu).

You can set the date format to any valid date/time format string. For example: F j, Y will format the dates in this format: “August 24, 2016”. See the WordPress Codex for more information.

This controls which data in your table is formatted as hyperlinks or plain text. This applies to the following columns: id, title, categories, tags, author, image as well as any custom taxonomy. Use links="all" to have all applicable columns have links, links="none" for no links, or any combination of the following keywords: idtitle, authorcategories, tags, terms or image as a comma-separated list.

If enabled for the id, title or image column, it will link to the post or page in question. For the author column, it will link to their author archive page. For tags, categories and custom terms, it will link to the relevant tag/category/term.

As an example, to have the title and image columns contain links, but not for other columns you would use: [posts_table columns="image,title,categories,tags" links="image,title"]


The message to display in the table if there are no posts found by your shortocde. Set this to any text, e.g. if you’re displaying products you could use: [posts_table no_posts_message="Sorry, no products found" post_type="product"]


The message to display if there are no records found after the user has entered a search term. For example: [posts_table no_posts_message="Sorry, no products match this search" post_type="product"]

Whether to show the column headings at the bottom of the table as well as the top. The default option is false (i.e. hide the footer headings), but you can set this to true to show them.


Certain data in the table can be displayed as links. (See the links option for more information about which columns display links). For example, the post author column can show a link to the relevant author page, and the categories column can link to the category archive for each category in the table.

Posts Table Pro provides a ‘search on click’ feature which means that instead of directing the user to the relevant page (e.g. the author page), it searches the table for that data instead.

For example, clicking on the author link “Pete Smith” would have the result of filtering the results in the table to only those posts written by Pete Smith. This is a quick way of filtering the results in the table. Defaults to true. To disable, set this to false.


This option tells the table whether to wrap long content onto multiple lines, or to keep everything on a single line and hide the rest. The default is true which means longer content will “wrap” onto extra lines as needed. If you set this to false it will ensure that each row is exactly one line high:
[posts_table columns="title,author,categories" wrap="false"]


This option is only relevant when displaying the table on smaller screen sizes (mobiles, tablets, etc) or when you have a lot of columns in your table and the plugin can’t fit everything in. When the screen size gets too small, the plugin will collapse certain columns down so they are no longer visible, and a “+” icon will appear at the left-side of each row. Clicking this icon will expand the row to show its full contents.

So the priorities option is used to determine the order in which columns are “collapsed” on smaller screens. Some default priorities are used, but if you wish to override these you can use this option. The lower the number, the higher priority that column has. So a column with a priority of “1” would have the highest priority and be collapsed last. If you had a table with three columns – title, author, and categories, and you wanted to make title the most important, categories second most, and author least important you would use the following: [posts_table columns="title,author,categories" priorities="1,3,2"]


Use this option to have more fine-grained control over the breakpoints for each column when viewed at smaller screen sizes. By default Posts Table Pro will show or hide columns on smaller screens based on the priorities option (or the default priorities if none are set). If you wish to set more specific breakpoints, you can set one of the following options for each column: desktop, tablet, mobile, all, none or default. For example, setting a breakpoint of tablet for a column means it will display on tablet devices, but not on mobiles or desktop screens.

The all option means the column will always be visible, regardless of screen size. The none option means it will not be shown in the table, but the column will still show in the child row (or modal) when expanded. The default option will let the plugin decide when it is hidden (using the priorities option if set).

You should set one option for each column in the table, for example:
[posts_table columns="title,content,tags,date" column_breakpoints="default,desktop,mobile,all"]


When the plugin can’t fit all the data within the space available (for example, on mobile devices) a “plus” icon appears to the left of each row to allow the user to show or expand the full content. This option sets whether that “+” icon control is displayed inside the first column (responsive_control="inline") or within its own separate column (responsive_control="column"). Defaults to inline.


This option determines how the “child rows” are displayed when viewing the table on smaller screen sizes (or when there is too much data to fit in the table). By default, the extra columns are displayed inside a child row which can be shown by clicking the “+” icon at the start of each row. You can also choose from the following options:

  • child_row – the default option. Extra data will be displayed in a hidden child row.
  • child_row_visible – Extra data is displayed in a child row which is expanded automatically when the table is first viewed.
  • modal – Extra data is displayed in a modal window when the “+” icon is clicked.


When paging between multiple pages of results in your table, Posts Table will automatically “jump” back to the top each time. This is particularly useful if you are displaying a large number of rows on each page. Posts Table attempts to scroll to the correct position on the page but sometimes it doesn’t quite calculate this correctly. This is because each website and WordPress theme is different and some can have features which interfere with the scroll position – e.g. sticky navigation menus.

The scroll_offset option lets you override the scroll amount or disable this behaviour altogether. The default scroll amount is 15. If you find that the top of your table is “chopped off” when moving between pages, try increasing this to a larger number (e.g. scroll_offset="50"). If you’d like to disable automatic scrolling, set this option to false.

Developer Documentation

There are a number of filters provided in Posts Table Pro which allow you to customise the behaviour of the plugin.


Use this to add a custom CSS class to every posts table. E.g.

add_filter( 'posts_table_custom_class', 'ptp_add_custom_class' );
function ptp_add_custom_class( $class ) {
    return 'my-class';


By default, Posts Table Pro will strip shortcodes from the post content so any content that would appear inside these shortcodes will not appear in the table. If you wish to override this behaviour, return true from this filter. Warning: processing shortcodes within your table can cause out of memory errors!

add_filter( 'posts_table_process_shortcodes', '__return_true' );


Filter which allows you to add custom data to the table, in addition to the standard columns provided by Posts Table Pro. It accepts two arguments: the custom data to return (defaults to an empty string) and the current post object.

For example, to add a custom column “rating” to your table, first add the custom column to your shortcode:
[posts_table columns="title,content,date,rating"]

Then add a filter to your theme or plugin to return this data:

add_filter( 'posts_table_custom_data_rating', 'ptp_add_custom_data_rating', 10, 2 );
function ptp_add_custom_data_rating( $value, $post ) {
    $value = 'xyz'; // set value as required
    return $value;


Filter which allows you to override a column heading for all posts tables on your site. If a custom heading is specified within the shortcode itself (in the columns option), then it will take priority over the value returned from this filter.

add_filter( 'posts_table_column_heading_title', 'ptp_custom_heading_title' );
function ptp_custom_heading_title( $heading ) {
    return 'My Title';


Filter which allows you to override a column priority for all posts tables on your site. If a priority is specified within the shortcode itself (using the priorities option), then it will take priority over the value returned from this filter.

add_filter( 'posts_table_column_priority_date', 'ptp_custom_priority_date' );
function ptp_custom_priority_date( $priority ) {
    return 10;


Filter which allows you to override a column width for all posts tables on your site. If a width is specified within the shortcode itself (using the widths option), then it will take priority over the value returned from this filter.

add_filter( 'posts_table_column_width_author', 'ptp_custom_width_author' );
function ptp_custom_width_author( $width ) {
    return '100px';


Filter which allows you to override the maximum posts limit (500 posts) set in Posts Table Pro. Note that this option only applies when you are not using the lazy_load option.

add_filter( 'posts_table_max_posts_limit', 'ptp_set_posts_limit' );
function ptp_set_posts_limit( $limit ) {
    return 2000;


Filter which allows you to override the query args passed to WP_Query prior to retrieving posts from the database. See WP_Query documentation for details.

STUCK? If you’re having any problems with Posts Table Pro, check out the troubleshooting page.