WordPress V5.0+Template Tag Reference Guide as of Version 5.2
Presented by DBS > Interactive Development :
Lists & Dropdown Tags
WP Dropdown Categorieswp_dropdown_categories();
Display or retrieve the HTML dropdown list of categories. Arguments are passed in as either an array or a query string.
$args = array( | ||||
'show_option_all' | => | '', | ||
'show_option_none' | => | '', | ||
'orderby' | => | 'ID', | ||
'order' | => | 'ASC', | ||
'show_count' | => | false, | ||
'hide_empty' | => | true, | ||
'child_of' | => | false, | ||
'exclude' | => | '', | ||
'echo' | => | true, | ||
'selected' | => | false, | ||
'hierarchical' | => | false, | ||
'name' | => | 'cat', | ||
'id' | => | '', | ||
'class' | => | 'postform', | ||
'depth' | => | 0, | ||
'tab_index' | => | 0, | ||
'taxonomy' | => | 'catetory', | ||
'hide_if_empty' | => | false | ||
); |
<?php wp_dropdown_categories($args); ?>
show_option_all
String • Default: ''
(Optional) Text to display for showing an 'all categories' option. Default will not show an option to select 'all categories'.
show_option_none
String • Default: ''
(Optional) Text to display for showing a 'no categories' option. Default will not show an option to select 'no categories'.
orderby
String • Default: 'ID'
(Optional) Column name to use for ordering the categories.
order
String • Default: 'ASC'
(Optional) Direction to sort categories. Valid values are 'ASC' and 'DESC'.
show_count
Boolean • Default: false
(Optional) Whether to show the post count in category.
hide_empty
Boolean • Default: true
(Optional) Whether to hide a category with no posts.
child_of
Boolean • Default: false
(Optional) Whether to display all categories that are descendants (i.e. children & grandchildren) of the category identified by its ID. If the parameter is used, the hide_empty parameter is effectively set to false.
exclude
String • Default: ''
(Optional) Category IDs to exclude. This parameter takes a comma-separated list of categories by unique ID, in ascending order.
echo
Boolean • Default: true
(Optional) Send output to browser (true) or return output to PHP (false).
selected
Integer • Default: 0
(Optional) Which category ID is selected.
hierarchical
Boolean • Default: false
(Optional) Display all categories (false) or display categories (true) to a depth of 'depth'.
name
String • Default: 'cat'
(Optional) The 'name' attribute value for select element.
id
String • Default: ''
(Optional) The 'id' attribute value for select element.
class
String • Default: 'postform'
(Optional) The 'class' attribute value for select element.
depth
Integer • Default: 0
(Optional) The max depth. This is ignored unless hierarchical is set to true.
tab_index
Integer • Default: 0
(Optional) The 'tabindex' attribute for the select element.
taxonomy
String • Default: 'category'
(Optional) Taxonomy to return. Valid values are 'category', 'post_tag' or any registered taxonomy.
hide_if_empty
Boolean • Default: false
(Optional) Hide dropdown (true) or show it (false) if no terms returned.
WP Dropdown Pages wp_dropdown_pages();
Displays a list of pages in a select (i.e dropdown) box with no submit button. Arguments are passed in as either an array or a query string.
$args = array( | ||||
'depth' | => | 0, | ||
'child_of' | => | 0, | ||
'selected' | => | 0, | ||
'echo' | => | true, | ||
'name' | => | 'page_id', | ||
'show_option_none' | => | , | ||
'exclude' | => | , | ||
'exclude_tree' | => | |||
); |
<?php wp_dropdown_pages($args); ?>
depth
Integer • Default: 0 (display all pages, including all sub-pages)
This parameter controls how many levels in the hierarchy of pages are to be included in the list generated by wp_list_pages. Valid values:
- 0 - Pages and sub-pages displayed in hierarchical (indented) form (Default).
- -1 - Pages in sub-pages displayed in flat (no indent) form.
- 1 - Show only top level Pages
- 2 - Value of 2 or greater specifies the depth/level to go to in displaying Pages.
child_of
Integer • Default: 0 (display all pages)
Displays the sub-pages of a single Page only; uses the ID for a Page as the value.
selected
Integer • Default: 0 (no page selected)
Page ID of the page to be 'selected' or presented in the display box.
echo
Boolean • Default: true
Toggles the display of the generated list of links or return the list as an HTML text string to be used in PHP. The default value is true (display the generated list items).
name
String • Default: 'page_id'
Name assigned to the dropdown form.
show_option_none
String • Default: none
Causes the HTML for the dropdown to allow you to select NONE of the pages.
exclude
String • Default: (exclude nothing)
Comma separated list of category IDs to exclude. For example, 'exclude=4,12' means category IDs 4 and 12 will NOT be displayed/echoed or returned.
exclude_tree
String • Default: (exclude nothing)
Define a parent Page ID to be excluded. Use this parameter to exclude a parent and all of that parent's child Pages. So 'exclude_tree=5' would exclude the parent Page 5, and its child Pages.
WP Dropdown Userswp_dropdown_users();
Create dropdown HTML content of users. Arguments are passed in as either an array or a query string.
$args = array( | ||||
'show_option_all' | => | null, | ||
'show_option_none' | => | null, | ||
'hide_if_only_one_author' | => | null, | ||
'orderby' | => | 'display_name', | ||
'order' | => | 'ASC', | ||
'include' | => | null, | ||
'exclude' | => | null, | ||
'multi' | => | false, | ||
'show' | => | 'display_name', | ||
'echo' | => | true, | ||
'selected' | => | false, | ||
'include_selected' | => | false, | ||
'name' | => | 'user', | ||
'id' | => | null, | ||
'class' | => | null, | ||
'blog_id' | => | $GLOBALS['blog_id'], | ||
'who' | => | null | ||
); |
<?php wp_dropdown_users($args); ?>
show_option_all
String • Default: null
Causes the HTML for the dropdown to allow you to select all of the users.
show_option_none
String • Default: null
Causes the HTML for the dropdown to allow you to select none of the users.
orderby
String • Default: 'display_name'
Key to sort options by. Valid values:
- 'ID'
- 'user_nicename'
- 'display_name'
order
String • Default: 'ASC'
Sort order for options. Valid values: 'ASC' or 'DESC'
include
String • Default: null
Comma separated list of users IDs to include. For example, 'include=4,12' means users IDs 4 and 12 will be displayed/echoed or returned. Defaults to null, which includes all.
exclude
String • Default: null
Comma separated list of users IDs to exclude. For example, 'exclude=4,12' means users IDs 4 and 12 will NOT be displayed/echoed or returned. Defaults to null, which excludes nothing.
multi
Boolean • Default: false
Whether to skip the ID attribute on the 'select' element.
show
String • Default: 'display_name'
User table column to display. If the selected item is empty then the user_login will be displayed in parenthesis.
- 'ID'
- 'user_login'
- 'display_name'
echo
Boolean • Default: true
Display users (true) or return them for use by PHP (false).
selected
Integer • Default: no user selected
User ID of the user to be 'selected' or presented in the display box.
include_selected
Boolean • Default:false
Always include the selected user ID in the dropdown.
name
String • Default: 'user'
Name assigned to the dropdown form.
id
String • Default: value of the 'name' parameter
ID attribute of select element.
class
String • Default: null
Class assinged to the dropdown form.
blog_id
Integer • Default: ID of current blog
ID of blog.
who
String • Default: all users • Introduced version 3.1
Which users to query. Currently only 'authors' is supported.
WP Get Archiveswp_get_archives();
This function displays a date-based archives list. This tag can be used anywhere within a template.
$args = array( | ||||
'type' | => | 'monthly', | ||
'limit' | => | , | ||
'format' | => | 'html', | ||
'before' | => | , | ||
'after' | => | , | ||
'show_post_count' | => | false, | ||
'echo' | => | true | ||
); |
<?php wp_get_archives($args); ?>
type
String • Default: 'monthly'
The type of archive list to display. Defaults to WordPress settings. Valid values:
- 'yearly'
- 'monthly'
- 'daily'
- 'weekly'
- 'postbypost' (posts ordered by post date)
- 'alpha' (same as postbypost but posts are ordered by post title)
limit
Integer • Default: (no limit)
Number of archives to get.
format
String • Default: 'html'
Format for the archive list. Valid values:
- 'html' - In HTML list (<li>) tags and before and after strings.
- 'option' - In select (<select>) or dropdown option (<option>) tags.
- 'link' - Within link (<link>) tags.
- 'custom' - Custom list using the before and after strings.
before
String • Default: none
Text to place before the link when using the html or custom for format option.
after
String • Default: none
Text to place after the link when using the html or custom for format option.
show_post_count
Boolean • Default: false
Displays number of posts in an archive or do not. For use with all types except 'postbypost'.
echo
Boolean • Default: true
Display output (true) or return it for use by PHP (false).
WP List Authorswp_list_authors();
Create dropdown HTML content of users. Arguments are passed in as either an array or a query string.
$args = array( | ||||
'orderby' | => | 'name', | ||
'order' | => | 'ASC', | ||
'number' | => | null, | ||
'optioncount' | => | false, | ||
'exclude_admin' | => | true, | ||
'show_fullname' | => | false, | ||
'hide_empty' | => | true, | ||
'echo' | => | true, | ||
'feed' | => | '', | ||
'feed_image' | => | '', | ||
'feed_type' | => | '', | ||
'style' | => | 'list', | ||
'html' | => | true | ||
); |
<?php wp_list_authors($args); ?>
orderby
String • Default: 'name'
Field to use to sort the results. This argument was introduced in Version 3.1.
Valid values:
- name - display_name from users table
- email - user_email from users table
- url - user_url from users table
- registered - user_registered date from users table
- id - ID from users table
- user_login - user_login from users table
- post_count - based on number of posts by user
order
String • Default: 'ASC'
Order of results either ascending or descending. This argument was introduced in Version 3.1. Valid values are 'ASC' and 'DESC'.
number
Integer • Default: null, meaning no limit
The maximum number of users to display. This argument was introduced in Version 3.1.
optioncount
Boolean • Default: false
Whether to display number of posts by each author.
exclude_admin
Boolean • Default: true
Exclude the 'admin' (login is admin) account from authors list.
show_fullname
Boolean • Default: false
Display the full (first and last) name of the authors. If false, the "Display name publicly as" is displayed.
hide_empty
Boolean • Default: true
Whether to hide authors with 0 posts.
echo
Boolean • Default: true
Echo the results (true) or return them as a value for a php variable (false).
feed
String • Default '' - (no feed displayed)
Text to display for a link to each author's RSS feed.
feed_image
String • Default '' - (no feed image displayed)
Path/filename for a graphic. This acts as a link to each author's RSS feed, and overrides the feed parameter.
feed_type
String • Default: '' - (no feed type)
The type of feed. Valid values:
- rss2
- atom
- rss
- rdf
style
String • Default: 'list'
Style in which to display the author list. A value of list, the default, displays the authors as an unordered list, while none generates no special display method (the list items are separated by comma). If html is false, this option is ignored. Valid values:
- list
- none
html
Boolean • Default: true
Whether to list the items in html or plaintext. The default setting is true. If html is false, the style setting is ignored and the items are returned, separated by comma.
WP List Categorieswp_list_categories();
Displays a list of Categories as links. When a Category link is clicked, all the posts in that Category will display on a Category Page using the appropriate Category Template dictated by the Template Hierarchy rules. Arguments are passed in as either an array or a query string.
$args = array( | ||||
'show_option_all' | => | '', | ||
'orderby' | => | 'name', | ||
'order' | => | 'ASC', | ||
'style' | => | 'list', | ||
'show_count' | => | false, | ||
'hide_empty' | => | true, | ||
'use_desc_for_title' | => | true, | ||
'child_of' | => | false, | ||
'feed' | => | '', | ||
'feed_type' | => | '', | ||
'feed_image' | => | '', | ||
'exclude' | => | '', | ||
'exclude_tree' | => | '', | ||
'include' | => | '', | ||
'hierarchical' | => | true, | ||
'title_li' | => | __('Categories'), | ||
'show_option_none' | => | __('No categories'), | ||
'number' | => | null, | ||
'echo' | => | true, | ||
'depth' | => | 0, | ||
'current_category' | => | 0, | ||
'pad_counts' | => | 0, | ||
'taxonomy' | => | 'catetory', | ||
'walker' | => | 'Walker_Category' | ||
); |
<?php wp_list_categories($args); ?>
show_option_all
String • Default: ''
(Optional) A non-blank value causes the display of a link to all categories if the style is set to list. The default value is not to display a link to all.
orderby
String • Default: 'ID'
(Optional) Sort categories alphabetically, by unique Category ID, or by the count of posts in that Category. The default is sort by category name. Valid values: 'ID', 'name', 'slug', 'count', and 'term_group'.
order
String • Default: 'ASC'
(Optional) Direction to sort categories. Valid values are 'ASC' and 'DESC'.
style
String • Default: 'list'
(Optional) Style to display the categories list in. A value of list displays the categories as list items while none generates no special display method (the list items are separated by <br> tags). The default setting is list (creates list items for an unordered list). Valid values: 'list' and 'none'.
show_count
Boolean • Default: false
(Optional) Whether to show the post count in category.
hide_empty
Boolean • Default: true
(Optional) Whether to hide a category with no posts.
use_desc_for_title
Boolean • Default: true
(Optional) Sets whether a category's description is inserted into the title attribute of the links created (i.e. <a title="<em>Category Description</em>" href="...).
child_of
Boolean • Default: false
(Optional) Whether to display all categories that are descendants (i.e. children & grandchildren) of the category identified by its ID. If the parameter is used, the hide_empty parameter is effectively set to false.
feed
String • Default: ''
(Optional) Display a link to each category's rss-2 feed and set the link text to display. The default is no text and no feed displayed.
feed_type
String • Default: ''
(Optional) The type of feed if one is used.
feed_image
String • Default: ''
(Optional) Set a URI for an image (usually an rss feed icon) to act as a link to each categories' rss-2 feed. This parameter overrides the feed parameter.
exclude
String • Default: ''
(Optional) Category IDs to exclude. This parameter takes a comma-separated list of categories by unique ID, in ascending order. The child_of parameter is automatically set to false.
exclude_tree
String • Default: ''
(Optional) Exclude category-tree from the results.
include
String • Default: ''
(Optional) Only include the categories detailed in a comma-separated list by unique ID, in ascending order.
hierarchical
Boolean • Default: true
(Optional) Display sub-categories as inner list items (below the parent list item)(true), or inline (false).
title_li
String • Default: 'Categories'
(Optional) Set the title and style of the outer list item. If present but empty, the outer list item will not be displayed.
show_option_none
String • Default: ''
(Optional) Text to display for showing a 'no categories' option. Default will not show an option to select 'no categories'.
number
Integer • Default: 0
(Optional) Sets the number of Categories to display. This causes the SQL LIMIT value to be defined. Default to no LIMIT.
echo
Boolean • Default: true
(Optional) Send output to browser (true) or return output to PHP (false).
depth
Integer • Default: 0
(Optional) This parameter controls how many levels in the hierarchy of Categories are to be included in the list of Categories. Possible values and their meanings:
- 0 - All Categories and child Categories
- -1 - All Categories displayed in flat (no indent) form (overrides hierarchical).
- 1 - Show only top level Categories
- n - Value of n (some number) specifies the depth (or level) to descend in displaying Categories
current_category
Integer • Default: 0
(Optional) Allows you to force the "current-cat" to appear on uses of wp_list_categories that are not on category archive pages. Normally, the current-cat is set only on category archive pages. If you have another use for it, or want to force it to highlight a different category, this overrides what the function thinks the "current" category is.
pad_counts
Boolean • Default: false
(Optional) Calculates link or post counts by including items from child categories. If show_counts and hierarchical are true this is automatically set to true.
taxonomy
String • Default: 'category'
(Optional) Taxonomy to return. Valid values are 'category', 'post_tag' or any registered taxonomy.
walker
Object • Default: none
(Optional) Walker class to render the list with - and instance of a class that extends either Walker_Category or Walker.
WP List Commentswp_list_comments();
Displays all comments for a post or Page based on a variety of parameters including ones set in the administration area. Arguments are passed in as either an array or a query string.
$args = array( | ||||
'walker' | => | null, | ||
'max_depth' | => | , | ||
'style' | => | 'ul', | ||
'callback' | => | null, | ||
'end-callback' | => | null, | ||
'type' | => | 'all', | ||
'page' | => | , | ||
'per_page' | => | , | ||
'avatar_size' | => | 32, | ||
'reverse_top_level' | => | null, | ||
'reverse_children' | => | false, | ||
'hierarchical' | => | null | ||
); |
<?php wp_list_comments($args); ?>
avatar_size
Integer • Default: 32
(Optional) Size that the avatar should be shown as, in pixels. http://gravatar.com/ supports sizes between 1 and 512.
style
String • Default: 'ul'
(Optional) Can be either 'div', 'ol', or 'ul', to display comments using divs, ordered, or unordered lists. Note that there are containing tags that must be written explicitly such as <div class="commentlist"><?php wp_list_comments(array('style' => 'div')); ?></div> or <ol class="commentlist"><?php wp_list_comments(array('style' => 'ol')); ?></ol>
type
String • Default: 'all'
(Optional) The type of comment(s) to display. Can be 'all', 'comment', 'trackback', 'pingback', or 'pings'. 'pings' is 'trackback' and 'pingback' together.
reply_text
String • Default: 'Reply'
(Optional) Text to display in each comment as a reply link. (This isn't an argument of this function but it gets passed to the get_comment_reply_link function.)
login_text
String • Default: 'Log in to Reply'
(Optional) Text to display in each comment if users must be registered and logged in to comment. (This isn't an argument of this function but it gets passed to the get_comment_reply_link function.)
callback
String • Default: null
(Optional) The name of a custom function to use to display each comment. Using this will make your custom function get called to display each comment, bypassing all internal WordPress functionality in this respect. Use to customize comments display for extreme changes to the HTML layout. Use with caution.
reverse_top_level
Boolean • Default: null
(Optional) Setting this to true will display the most recent comment first then going back in order.
reverse_children
Boolean • Default: null
(Optional) Setting this to true will display the children (reply level comments) with the most recent ones first, then going back in order.
WP List Pages wp_list_pages();
Displays a list of WordPress Pages as links. It is often used to customize the Sidebar or Header, but may be used in other Templates as well. Arguments are passed in as either an array or a query string.
$args = array( | ||||
'depth' | => | 0, | ||
'show_date' | => | '', | ||
'date_format' | => | get_option('date_format'), | ||
'child_of' | => | 0, | ||
'exclude' | => | '', | ||
'include' | => | '', | ||
'title_li' | => | __('Pages'), | ||
'echo' | => | true, | ||
'authors' | => | '', | ||
'sort_column' | => | 'menu_order, post_title', | ||
'link_before' | => | '', | ||
'link_after' | => | '', | ||
'exclude_tree' | => | '', | ||
'post_type' | => | 'page', | ||
'post_status' | => | 'publish' | ||
); |
<?php wp_list_pages($args); ?>
depth
Integer • Default: 0
(Optional) This parameter controls how many levels in the hierarchy of pages are to be included in the list generated. Valid values:
- 0 - Displays pages at any depth and arranges them hierarchically in nested lists
- -1 - Displays pages at any depth and arranges them in a single, flat list
- 1 - Displays top-level Pages only
- 2, 3 ... etc - Displays Pages to the given depth
show_date
String • Default: ''
(Optional) Display creation or last modified date next to each Page. Valid values:
- '' - Display no date.
- 'modified' - Display the date last modified.
- 'xxx' - Any value other than modified displays the date (post_date) the Page was first created.
date_format
String • Default: ''
(Optional) Controls the format of the Page date set by the show_date parameter (example: "l, F j, Y"). This parameter defaults to the date format configured in your WordPress options.
child_of
Integer • Default: 0 (displays all Pages)
(Optional) Displays the sub-pages of a single Page only; uses the ID for a Page as the value. Note that the child_of parameter will also fetch "grandchildren" of the given ID, not just direct descendants.
exclude
String • Default: ''
(Optional) Define a comma-separated list of Page IDs to be excluded from the list (example: 'exclude=3,7,31').
include
String • Default: ''
(Optional) Only include certain Pages in the list generated by wp_list_pages. Like exclude, this parameter takes a comma-separated list of Page IDs.
title_li
String • Default: __('Pages') , which displays "Pages" (the __('') is used for localization purposes)
(Optional) Set the title and style of the outer list item. If present but empty, the outer list item will not be displayed.
echo
Boolean • Default: true
(Optional) Toggles the display of the generated list of links (true) or return the list as an HTML text string to be used in PHP (false).
authors
String • Default: ''
(Optional) Only include Pages authored by the authors in this comma-separated list of author IDs. If no authors are specified, all authors are included.
sort_column
String • Default: 'post_title'
(Optional) Sorts the list of Pages in a number of different ways. Note: The sort_column parameter can be used to sort the list of Pages by the descriptor of any field in the wp_post table of the WordPress database. Some useful examples are listed here:
- 'post_title' - Sort Pages alphabetically (by title).
- 'menu_order' - Sort Pages by Page Order. Note the difference between Page Order and Page ID. The Page ID is a unique number assigned by WordPress to every post or page. The Page Order can be set by the user in the Pages->Edit panel.
- 'post_date' - Sort by creation time.
- 'post_modified' - Sort by time last modified.
- 'ID' - Sort by numeric Page ID.
- 'post_author' - Sort by the Page author's numeric ID.
- 'post_name' - Sort alphabetically by Post slug.
link_before
String • Default: ''
(Optional) Sets the text or html that precedes the link text inside <a> tag.
link_after
String • Default: ''
(Optional) Sets the text or html that follows the link text inside <a> tag.
exclude_tree
String • Default: ''
(Optional) Define a comma-separated list of parent Page IDs to be excluded. Use this parameter to exclude a parent and all of that parent's child Pages. So 'exclude_tree=5' would exclude the parent Page 5, and its child (all descendant) Pages.
post_type
String • Default: 'page'
(Optional) List custom post types.
post_status
String • Default: 'publish'
(Optional) a comma-separated list of all post status types to return. For example: 'publish,private'.
WP Page Menu wp_page_menu();
Displays a list of WordPress Pages as links, and affords the opportunity to have Home added automatically to the list of Pages displayed. This Tag is useful to customize the Sidebar or Header, but may be used in other Templates as well. Arguments are passed in as either an array or a query string.
$args = array( | ||||
'sort_column' | => | 'menu_order, post_title', | ||
'menu_class' | => | 'menu', | ||
'include' | => | '', | ||
'exclude' | => | '', | ||
'echo' | => | true, | ||
'show_home' | => | false, | ||
'link_before' | => | '', | ||
'link_after' | => | '' | ||
); |
<?php wp_page_menu($args); ?>
sort_column
String • Default: 'menu_order, post_title' - which means sort by menu order and alphabetically by page title
(Optional) Sorts the list of Pages in a number of different ways. Note: The sort_column parameter can be used to sort the list of Pages by the descriptor of any field in the wp_post table of the WordPress database. Some useful examples are listed here:
- 'post_title' - Sort Pages alphabetically (by title).
- 'menu_order' - Sort Pages by Page Order. Note the difference between Page Order and Page ID. The Page ID is a unique number assigned by WordPress to every post or page. The Page Order can be set by the user in the Pages->Edit panel.
- 'post_date' - Sort by creation time.
- 'post_modified' - Sort by time last modified.
- 'ID' - Sort by numeric Page ID.
- 'post_author' - Sort by the Page author's numeric ID.
- 'post_name' - Sort alphabetically by Post slug.
menu_class
String • Default: 'menu'
(Optional) The div class the list is displayed in.
include
String • Default: ''
(Optional) Only list pages identified with the corresponding IDs, i.e. wp_page_menu('include=2,14') will list only pages with id's 2 and 14.
exclude
String • Default: ''
(Optional) Define a comma-separated list of Page IDs to be excluded from the list (example: 'exclude=3,7,31').
echo
Boolean • Default: true
(Optional) Toggles the display of the generated list of links (true) or return the list as an HTML text string to be used in PHP (false).
show_home
Mixed • Default: false
(Optional) Add "Home" as the first item in the list of "Pages". The URL assigned to "Home" is pulled from the Blog address (URL) in Administration > Settings > General. Instead of true or false, you can assign any text and that text will be used as the link in place of the word "Home" - and this parameter will still parse to true.
link_before
String • Default: ''
(Optional) Sets the text or html that precedes the link text inside <a> tag.
link_after
String • Default: ''
(Optional) Sets the text or html that follows the link text inside <a> tag.