wp_list_categories( array|string $args = '' )

Display or retrieve the HTML list of categories.

Contents

Description Description

Parameters 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|array) ID of category, or array of IDs of categories, that should get the 'current-cat' class. Default 0.
  • 'depth'
    (int) Category depth. Used for tab indentation. Default 0.
  • 'echo'
    (bool|int) True to echo markup, false to return it. Default 1.
  • 'exclude'
    (array|string) Array 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'
    (array|string) Array or comma/space-separated string of term IDs to exclude, along with their descendants. See get_terms().
  • 'feed'
    (string) Text to use for the feed link. Default 'Feed for all posts filed under [cat name]'.
  • 'feed_image'
    (string) URL of an image to use for the feed link.
  • 'feed_type'
    (string) Feed type. Used to build feed link. See get_term_feed_link(). Default empty string (default feed).
  • 'hide_title_if_empty'
    (bool) Whether to hide the $title_li element if there are no terms in the list. Default false (title will always be shown).
  • 'separator'
    (string) Separator between links. Default <br />.
  • 'show_count'
    (bool|int) Whether to show how many posts are in the category. Default 0.
  • 'show_option_all'
    (string) Text to display for showing all categories.
  • 'show_option_none'
    (string) Text to display for the 'no categories' option. Default 'No categories'.
  • 'style'
    (string) The 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 <br> tags. Default 'list'.
  • 'title_li'
    (string) Text to use for the list title <li> element. Pass an empty string to disable. Default 'Categories'.
  • 'use_desc_for_title'
    (bool|int) Whether to use the category description as the title attribute. Default 1.

Default value: ''

Top ↑

Return Return

(false|string) HTML list of categories only if 'echo' argument is 0.

Top ↑

Source Source

File: wp-includes/category-template.php 

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'  => 1,
	);

	$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 ) && ! in_array( 'page', $taxonomy_object->object_type ) ) {
				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  $args   An array of taxonomy-listing arguments.
	 */
	$html = apply_filters( 'wp_list_categories', $output, $args );

	if ( $parsed_args['echo'] ) {
		echo $html;
	} else {
		return $html;
	}
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
4.4.0 The current_category argument was modified to optionally accept an array of values.
2.1.0 Introduced.

Top ↑

More Information More Information

If you need a function that does not format the results, try get_categories().

Top ↑

Usage 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

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/category-template.php: walk_category_tree()

Retrieve HTML list content for category list.
wp-includes/category-template.php: wp_list_categories

Filters the HTML output of a taxonomy list.
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/formatting.php: esc_attr()

Escaping for HTML attributes.
wp-includes/formatting.php: esc_url()

Checks and cleans a URL.
wp-includes/query.php: is_category()

Determines whether the query is for an existing category archive page.
wp-includes/query.php: is_tag()

Determines whether the query is for an existing tag archive page.
wp-includes/query.php: is_tax()

Determines whether the query is for an existing custom taxonomy archive page.
wp-includes/query.php: get_queried_object()

Retrieve the currently-queried object.
wp-includes/query.php: get_queried_object_id()

Retrieve ID of the current queried object.
wp-includes/category.php: get_categories()

Retrieve list of category objects.
wp-includes/functions.php: wp_parse_args()

Merge user defined arguments into defaults array.
wp-includes/functions.php: wp_parse_id_list()

Clean up an array, comma- or space-separated list of IDs.
wp-includes/taxonomy.php: taxonomy_exists()

Determines whether the taxonomy name exists.
wp-includes/taxonomy.php: get_taxonomy()

Retrieves the taxonomy object of $taxonomy.
wp-includes/link-template.php: home_url()

Retrieves the URL for the current site where the front end is accessible.
wp-includes/link-template.php: get_post_type_archive_link()

Retrieves the permalink for a post type archive.
wp-includes/link-template.php: get_permalink()

Retrieves the full permalink for the current post or post ID.
wp-includes/plugin.php: apply_filters()

Calls the callback functions that have been added to a filter hook.
wp-includes/option.php: get_option()

Retrieves an option value based on an option name.
wp-includes/post.php: get_post_type_object()

Retrieves a post type object by name.
Show 16 more uses Hide more uses

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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.

    $taxonomy = 'category';

// Get the term IDs assigned to post.
$post_terms = wp_get_object_terms( $post->ID, $taxonomy, array( 'fields' => 'ids' ) );

// Separator between links.
$separator = ', ';

if ( ! empty( $post_terms ) && ! is_wp_error( $post_terms ) ) {

	$term_ids = implode( ',' , $post_terms );

	$terms = wp_list_categories( array(
		'title_li' => '',
		'style'    => 'none',
		'echo'     => false,
		'taxonomy' => $taxonomy,
		'include'  => $term_ids
	) );

	$terms = rtrim( trim( str_replace( '<br />',  $separator, $terms ) ), $separator );

	// Display post categories.
	echo  $terms;
}

    Expand full source codeCollapse full source code

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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:

    <ul>
	<?php wp_list_categories( array(
		'orderby' => 'name',
		'include' => array( 3, 5, 9, 16 )
	) ); ?> 
</ul>

    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.

    <ul>
	<?php wp_list_categories( array(
		'orderby'    => 'name',
		'show_count' => true,
		'exclude'    => array( 10 )
	) ); ?> 
</ul>
  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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:

    <ul>
	<?php wp_list_categories( array(
		'exclude'  => array( 4,7 ),
		'title_li' => ''
	) ); ?>
</ul>

    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 :

    <ul>
	<?php wp_list_categories( array(
		'include'  => array( 5, 9, 23 ),
		'title_li' => '<h2>' . __( 'Poetry', 'textdomain' ) . '</h2>'
	) ); ?> 
</ul>
  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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:

    // List terms in a given taxonomy using wp_list_categories (also useful as a widget if using a PHP Code plugin)

$taxonomy     = 'genre';
$orderby      = 'name'; 
$show_count   = false;
$pad_counts   = false;
$hierarchical = true;
$title        = '';

$args = array(
  'taxonomy'     => $taxonomy,
  'orderby'      => $orderby,
  'show_count'   => $show_count,
  'pad_counts'   => $pad_counts,
  'hierarchical' => $hierarchical,
  'title_li'     => $title
);
?>

<ul>
	<?php wp_list_categories( $args ); ?>
</ul>

    Expand full source codeCollapse full source code

  6. Skip to note 6 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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.

    $variable = wp_list_categories( array(
	'echo' => false,
	'show_count' => true,
	'title_li' => '<h2>' . __( 'Categories', 'textdomain' ) . '</h2>'
) );

$variable = preg_replace( '~\((\d+)\)(?=\s*+<)~', '$1', $variable );
echo $variable;
  7. Skip to note 7 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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.

    <ul>
	<?php wp_list_categories( array(
		'orderby'            => 'id',
		'show_count'         => true,
		'use_desc_for_title' => false,
		'child_of'           => 8
	) ); ?>
</ul>
  8. Skip to note 8 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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.

    <ul>
	<?php wp_list_categories( array(
		'orderby'    => 'name',
		'show_count' => true,
		'feed'       => 'RSS'
	) ); ?>
</ul>

    To replace the rss link with a feed icon, you could write:

    <ul>
	<?php wp_list_categories( array(
		'orderby'    => 'name',
		'show_count' => true,
		'feed_image' => '/images/rss.gif'
	) ); ?>
</ul>
  9. Skip to note 9 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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 :

     li.categories { ... }  /* outermost list item */
 li.cat-item { ... }
 li.cat-item-7 { ... }  /* category ID #7, etc */
 li.current-cat { ... }
 li.current-cat-parent { ... }
 ul.children { ... }

You must log in before being able to contribute a note or feedback.