wp_list_categories( array|string $args = '' ): void|string|false
Displays or retrieves the HTML list of categories.
Contents
Parameters
-
$args
array|string Optional -
Array of optional arguments. See get_categories() , get_terms() , and WP_Term_Query::__construct() for information on additional accepted arguments.
current_category
int|int[]ID of category, or array of IDs of categories, that should get the'current-cat'
class. Default 0.depth
intCategory depth. Used for tab indentation. Default 0.echo
bool|intWhether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents. Default 1.exclude
int[]|stringArray or comma/space-separated string of term IDs to exclude.
If$hierarchical
is true, descendants of$exclude
terms will also be excluded; see$exclude_tree
. See get_terms() .
exclude_tree
int[]|stringArray or comma/space-separated string of term IDs to exclude, along with their descendants. See get_terms() .feed
stringText to use for the feed link. Default 'Feed for all posts filed under [cat name]'.feed_image
stringURL of an image to use for the feed link.feed_type
stringhide_title_if_empty
boolWhether to hide the$title_li
element if there are no terms in the list. Default false (title will always be shown).separator
stringSeparator between links. Default<br />
.show_count
bool|intWhether to include post counts. Accepts 0, 1, or their bool equivalents.
Default 0.show_option_all
stringText to display for showing all categories.show_option_none
stringText to display for the 'no categories' option.
Default 'No categories'.style
stringThe style used to display the categories list. If'list'
, categories will be output as an unordered list. If left empty or another value, categories will be output separated by
tags. Default
'list'
.taxonomy
stringName of the taxonomy to retrieve. Default'category'
.title_li
stringText to use for the list title<li>
element. Pass an empty string to disable. Default'Categories'
.use_desc_for_title
bool|intWhether to use the category description as the title attribute.
Accepts 0, 1, or their bool equivalents. Default 0.walker
WalkerWalker object to use to build the output. Default empty which results in a Walker_Category instance being used.
More Arguments from get_categories( ... $args )
Array or query string of term query parameters.
taxonomy
string|string[]Taxonomy name, or array of taxonomy names, to which results should be limited.object_ids
int|int[]Object ID, or array of object IDs. Results will be limited to terms associated with these objects.orderby
stringField(s) to order terms by. Accepts:
- Term fields (
'name'
,'slug'
,'term_group'
,'term_id'
,'id'
,'description'
,'parent'
,'term_order'
). Unless$object_ids
is not empty,'term_order'
is treated the same as'term_id'
. 'count'
to use the number of objects associated with the term.'include'
to match the'order'
of the$include
param.'slug__in'
to match the'order'
of the$slug
param.'meta_value'
'meta_value_num'
.- The value of
$meta_key
. - The array keys of
$meta_query
. 'none'
to omit the ORDER BY clause.
'name'
.- Term fields (
order
stringWhether to order terms in ascending or descending order.
Accepts'ASC'
(ascending) or'DESC'
(descending).
Default'ASC'
.hide_empty
bool|intWhether to hide terms not assigned to any posts. Accepts1|true
or0|false
. Default1|true
.include
int[]|stringArray or comma/space-separated string of term IDs to include.
Default empty array.exclude
int[]|stringArray or comma/space-separated string of term IDs to exclude.
If$include
is non-empty,$exclude
is ignored.
Default empty array.exclude_tree
int[]|stringArray or comma/space-separated string of term IDs to exclude along with all of their descendant terms. If$include
is non-empty,$exclude_tree
is ignored. Default empty array.number
int|stringMaximum number of terms to return. Accepts
(all) or any positive number. Default''
|0
(all). Note that''
|0$number
may not return accurate results when coupled with$object_ids
.
See #41796 for details.offset
intThe number by which to offset the terms query.fields
stringTerm fields to query for. Accepts:
'all'
Returns an array of complete term objects (WP_Term[]
).'all_with_object_id'
Returns an array of term objects with the'object_id'
param (WP_Term[]
). Works only when the$object_ids
parameter is populated.'ids'
Returns an array of term IDs (int[]
).'tt_ids'
Returns an array of term taxonomy IDs (int[]
).'names'
Returns an array of term names (string[]
).'slugs'
Returns an array of term slugs (string[]
).'count'
Returns the number of matching terms (int
).'id=>parent'
Returns an associative array of parent term IDs, keyed by term ID (int[]
).'id=>name'
Returns an associative array of term names, keyed by term ID (string[]
).'id=>slug'
Returns an associative array of term slugs, keyed by term ID (string[]
).
'all'
.count
boolWhether to return a term count. If true, will take precedence over$fields
. Default false.name
string|string[]Name or array of names to return term(s) for.
slug
string|string[]Slug or array of slugs to return term(s) for.
term_taxonomy_id
int|int[]Term taxonomy ID, or array of term taxonomy IDs, to match when querying terms.hierarchical
boolWhether to include terms that have non-empty descendants (even if$hide_empty
is set to true). Default true.search
stringSearch criteria to match terms. Will be SQL-formatted with wildcards before and after.name__like
stringRetrieve terms with criteria by which a term is LIKE$name__like
.description__like
stringRetrieve terms where the description is LIKE$description__like
.pad_counts
boolWhether to pad the quantity of a term's children in the quantity of each term's "count" object variable. Default false.get
stringWhether to return terms regardless of ancestry or whether the terms are empty. Accepts'all'
or''
(disabled). Default''
.child_of
intTerm ID to retrieve child terms of. If multiple taxonomies are passed,$child_of
is ignored. Default 0.parent
intParent term ID to retrieve direct-child terms of.
childless
boolTrue to limit results to terms that have no children.
This parameter has no effect on non-hierarchical taxonomies.
Default false.cache_domain
stringUnique cache key to be produced when this query is stored in an object cache. Default'core'
.update_term_meta_cache
boolWhether to prime meta caches for matched terms. Default true.meta_key
string|string[]Meta key or keys to filter by.meta_value
string|string[]Meta value or values to filter by.meta_compare
stringMySQL operator used for comparing the meta value.
See WP_Meta_Query::__construct() for accepted values and default value.meta_compare_key
stringMySQL operator used for comparing the meta key.
See WP_Meta_Query::__construct() for accepted values and default value.meta_type
stringMySQL data type that the meta_value column will be CAST to for comparisons.
See WP_Meta_Query::__construct() for accepted values and default value.meta_type_key
stringMySQL data type that the meta_key column will be CAST to for comparisons.
See WP_Meta_Query::__construct() for accepted values and default value.meta_query
arrayAn associative array of WP_Meta_Query arguments.
See WP_Meta_Query::__construct() for accepted values.
Default:
''
Return
void|string|false Void if 'echo'
argument is true, HTML list of categories if 'echo'
is false.
False if the taxonomy does not exist.
More Information
If you need a function that does not format the results, try get_categories() .
Usage
By default, wp_list_categories() displays:
- No link to all categories
- Sorts the list of Categories by the Category name in ascending order
- Displayed in an unordered list style
- Does not show the post count
- Displays only Categories with posts
- Sets the title attribute to the Category Description
- Is not restricted to the child_of any Category
- No feed or feed image used
- Does not exclude any Category and includes all Categories
- Displays the active Category with the CSS Class-Suffix ‘ current-cat’
- Shows the Categories in hierarchical indented fashion
- Display Category as the heading over the list
- No SQL LIMIT is imposed (‘number’ => 0 is not shown above)
- Displays (echos) the categories
- No limit to depth
- All categories.
- The list is rendered using a new walker object of the the Walker_Category class
Source
File: wp-includes/category-template.php
.
View all references
function wp_list_categories( $args = '' ) {
$defaults = array(
'child_of' => 0,
'current_category' => 0,
'depth' => 0,
'echo' => 1,
'exclude' => '',
'exclude_tree' => '',
'feed' => '',
'feed_image' => '',
'feed_type' => '',
'hide_empty' => 1,
'hide_title_if_empty' => false,
'hierarchical' => true,
'order' => 'ASC',
'orderby' => 'name',
'separator' => '<br />',
'show_count' => 0,
'show_option_all' => '',
'show_option_none' => __( 'No categories' ),
'style' => 'list',
'taxonomy' => 'category',
'title_li' => __( 'Categories' ),
'use_desc_for_title' => 0,
);
$parsed_args = wp_parse_args( $args, $defaults );
if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) {
$parsed_args['pad_counts'] = true;
}
// Descendants of exclusions should be excluded too.
if ( true == $parsed_args['hierarchical'] ) {
$exclude_tree = array();
if ( $parsed_args['exclude_tree'] ) {
$exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $parsed_args['exclude_tree'] ) );
}
if ( $parsed_args['exclude'] ) {
$exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $parsed_args['exclude'] ) );
}
$parsed_args['exclude_tree'] = $exclude_tree;
$parsed_args['exclude'] = '';
}
if ( ! isset( $parsed_args['class'] ) ) {
$parsed_args['class'] = ( 'category' === $parsed_args['taxonomy'] ) ? 'categories' : $parsed_args['taxonomy'];
}
if ( ! taxonomy_exists( $parsed_args['taxonomy'] ) ) {
return false;
}
$show_option_all = $parsed_args['show_option_all'];
$show_option_none = $parsed_args['show_option_none'];
$categories = get_categories( $parsed_args );
$output = '';
if ( $parsed_args['title_li'] && 'list' === $parsed_args['style']
&& ( ! empty( $categories ) || ! $parsed_args['hide_title_if_empty'] )
) {
$output = '<li class="' . esc_attr( $parsed_args['class'] ) . '">' . $parsed_args['title_li'] . '<ul>';
}
if ( empty( $categories ) ) {
if ( ! empty( $show_option_none ) ) {
if ( 'list' === $parsed_args['style'] ) {
$output .= '<li class="cat-item-none">' . $show_option_none . '</li>';
} else {
$output .= $show_option_none;
}
}
} else {
if ( ! empty( $show_option_all ) ) {
$posts_page = '';
// For taxonomies that belong only to custom post types, point to a valid archive.
$taxonomy_object = get_taxonomy( $parsed_args['taxonomy'] );
if ( ! in_array( 'post', $taxonomy_object->object_type, true ) && ! in_array( 'page', $taxonomy_object->object_type, true ) ) {
foreach ( $taxonomy_object->object_type as $object_type ) {
$_object_type = get_post_type_object( $object_type );
// Grab the first one.
if ( ! empty( $_object_type->has_archive ) ) {
$posts_page = get_post_type_archive_link( $object_type );
break;
}
}
}
// Fallback for the 'All' link is the posts page.
if ( ! $posts_page ) {
if ( 'page' === get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) ) {
$posts_page = get_permalink( get_option( 'page_for_posts' ) );
} else {
$posts_page = home_url( '/' );
}
}
$posts_page = esc_url( $posts_page );
if ( 'list' === $parsed_args['style'] ) {
$output .= "<li class='cat-item-all'><a href='$posts_page'>$show_option_all</a></li>";
} else {
$output .= "<a href='$posts_page'>$show_option_all</a>";
}
}
if ( empty( $parsed_args['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) {
$current_term_object = get_queried_object();
if ( $current_term_object && $parsed_args['taxonomy'] === $current_term_object->taxonomy ) {
$parsed_args['current_category'] = get_queried_object_id();
}
}
if ( $parsed_args['hierarchical'] ) {
$depth = $parsed_args['depth'];
} else {
$depth = -1; // Flat.
}
$output .= walk_category_tree( $categories, $depth, $parsed_args );
}
if ( $parsed_args['title_li'] && 'list' === $parsed_args['style']
&& ( ! empty( $categories ) || ! $parsed_args['hide_title_if_empty'] )
) {
$output .= '</ul></li>';
}
/**
* Filters the HTML output of a taxonomy list.
*
* @since 2.1.0
*
* @param string $output HTML output.
* @param array|string $args An array or query string of taxonomy-listing arguments. See
* wp_list_categories() for information on accepted arguments.
*/
$html = apply_filters( 'wp_list_categories', $output, $args );
if ( $parsed_args['echo'] ) {
echo $html;
} else {
return $html;
}
}
Hooks
-
apply_filters( 'wp_list_categories',
string $output ,array|string $args ) -
Filters the HTML output of a taxonomy list.
Changelog
Version | Description |
---|---|
6.1.0 | Default value of the 'use_desc_for_title' argument was changed from 1 to 0. |
4.4.0 | The current_category argument was modified to optionally accept an array of values. |
2.1.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Display Categories Assigned to a Post
Display the categories (or terms from other taxonomies) assigned to a post ordered by parent-child category relationship. Similar to the function get_the_category_list() which orders the categories by name. This example must be used inside the loop.
Include or Exclude Categories
To sort categories alphabetically and include only the categories with IDs of 16, 3, 9 and 5, you could write the following code:
The following example displays category links sorted by name, shows the number of posts for each category, and excludes the category with the ID of 10 from the list.
Display or Hide the List Heading
The title_li parameter sets or hides a title or heading for the category list generated by wp_list_categories. It defaults to ‘(__(‘Categories’)’, i.e. it displays the word “Categories” as the list’s heading. If the parameter is set to a null or empty value, no heading is displayed. The following example code excludes categories with IDs 4 and 7 and hides the list heading:
In the following example, only Categories with IDs 9, 5, and 23 are included in the list and the heading text has been changed to the word “Poetry”, with a heading style of :
Note that you can use all the arguments implemented for get_terms() function and WP_Term_Query::__construct. So, for example, the arguments
meta_key
ormeta_value
can be added and will do their job as well.Remove Parentheses from Category Counts
When show_count=1, each category count is surrounded by parentheses. In order to remove the parentheses without modifying core WordPress files, use the following code.
Display Terms in a custom taxonomy
With Version 3.0 the taxonomy parameter was added to enable wp_list_categories() function to list Custom Taxonomies. This example list the terms in the taxonomy genre:
All categories divided by comma.
Only Show Children of a Category
The following example code generates category links, sorted by ID, only for the children of the category with ID 8; it shows the number of posts per category and hides category descriptions from the title attribute of the generated links. Note: If there are no posts in a parent Category, the parent Category will not display.
Display Categories with RSS Feed Links
The following example generates Category links sorted by name, shows the number of posts per Category, and displays links to the RSS feed for each Category.
To replace the rss link with a feed icon, you could write:
Markup and Styling of Category Lists
By default, wp_list_categories() generates nested unordered lists (ul) within a single list item (li) titled “Categories”.
You can remove the outermost item and list by setting the title_li parameter to an empty string. You’ll need to wrap the output in an ordered list (ol) or unordered list yourself (see the examples above). If you don’t want list output at all, set the style parameter to none.
You can style the output with these CSS selectors :
‘include’ is missing from the parameter list.
Top ↑
Feedback
This code is a variation of one that already appears here that the last two arrays show the child categories of 17 and then exclude the main category showing only the children.
— By Artgallery75 —
‘hierarchical’ is missing from the parameter list. — By nicholas.eymann —