wp_list_categories( array|string $args = '' ): void|string|false

Parameters

$argsarray|stringoptional

Array of optional arguments. See get_categories(), get_terms(), and WP_Term_Query::__construct() for information on additional accepted arguments.Default: ''

• $current_categoryint|int[]default: 0

  ID of category, or array of IDs of categories, that should get the 'current-cat' class.

• $depthintdefault: 0

  Category depth. Used for tab indentation.

• $echobool|intdefault: 1

  Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents.

• $excludeint[]|stringdefault: empty 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_treeint[]|stringdefault: empty string

  Array or comma/space-separated string of term IDs to exclude, along with their descendants. See get_terms().

• $feedstringdefault: 'Feed for all posts filed under [cat name]'

  Text to use for the feed link.

• $feed_imagestringdefault: empty string

  URL of an image to use for the feed link.

• $feed_typestringdefault: empty string (default feed)

  Feed type. Used to build feed link. See get_term_feed_link().

• $hide_title_if_emptybooldefault: false (title will always be shown)

  Whether to hide the $title_li element if there are no terms in the list.

• $separatorstringdefault: ' '

  Separator between links.

• $show_countbool|intdefault: 0

  Whether to include post counts. Accepts 0, 1, or their bool equivalents.

• $show_option_allstringdefault: empty string

  Text to display for showing all categories.

• $show_option_nonestringdefault: 'No categories'

  Text to display for the 'no categories' option.

• $stylestringdefault: 'list'

  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.

• $taxonomystringdefault: 'category'

  Name of the taxonomy to retrieve.

• $title_listringdefault: 'Categories'

  Text to use for the list title <li> element. Pass an empty string to disable.

• $use_desc_for_titlebool|intdefault: 0

  Whether to use the category description as the title attribute. Accepts 0, 1, or their bool equivalents.

• $walkerWalkerdefault: empty which results in a Walker_Category instance being used

  Walker object to use to build the output.

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.

Hooks fired · 1

One hook fires while wp_list_categories() runs, in this order:

1. 1
   apply_filters( wp_list_categories )filterline 681 (+143 into the body)

   Filters the HTML output of a taxonomy list.

Uses · 20

• __()Retrieves the translation of $text.
• wp_parse_args()Merges user defined arguments into defaults array.
• wp_parse_id_list()Cleans up an array, comma- or space-separated list of IDs.
• taxonomy_exists()Determines whether the taxonomy name exists.
• get_categories()Retrieves a list of category objects.
• esc_attr()Escaping for HTML attributes.
• get_taxonomy()Retrieves the taxonomy object of $taxonomy.
• get_post_type_object()Retrieves a post type object by name.
• get_post_type_archive_link()Retrieves the permalink for a post type archive.
• get_option()Retrieves an option value based on an option name.
• get_permalink()Retrieves the full permalink for the current post or post ID.
• home_url()Retrieves the URL for the current site where the front end is accessible.

Used by · 3

• WP_Widget_Categories::widget()Outputs the content for the current Categories widget instance.
• render_block_core_categories()Renders the `core/categories` block on server.
• wp_list_cats()Lists categories.

Source

View on Trac ↗View on GitHub ↗

538function wp_list_categories( $args = '' ) {539	$defaults = array(540		'child_of'            => 0,541		'current_category'    => 0,542		'depth'               => 0,543		'echo'                => 1,544		'exclude'             => '',545		'exclude_tree'        => '',546		'feed'                => '',547		'feed_image'          => '',548		'feed_type'           => '',549		'hide_empty'          => 1,550		'hide_title_if_empty' => false,551		'hierarchical'        => true,552		'order'               => 'ASC',553		'orderby'             => 'name',554		'separator'           => '<br />',555		'show_count'          => 0,556		'show_option_all'     => '',557		'show_option_none'    => __( 'No categories' ),558		'style'               => 'list',559		'taxonomy'            => 'category',560		'title_li'            => __( 'Categories' ),561		'use_desc_for_title'  => 0,562	);563 564	$parsed_args = wp_parse_args( $args, $defaults );565 566	if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) {567		$parsed_args['pad_counts'] = true;568	}569 570	// Descendants of exclusions should be excluded too.571	if ( $parsed_args['hierarchical'] ) {572		$exclude_tree = array();573 574		if ( $parsed_args['exclude_tree'] ) {575			$exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $parsed_args['exclude_tree'] ) );576		}577 578		if ( $parsed_args['exclude'] ) {579			$exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $parsed_args['exclude'] ) );580		}581 582		$parsed_args['exclude_tree'] = $exclude_tree;583		$parsed_args['exclude']      = '';584	}585 586	if ( ! isset( $parsed_args['class'] ) ) {587		$parsed_args['class'] = ( 'category' === $parsed_args['taxonomy'] ) ? 'categories' : $parsed_args['taxonomy'];588	}589 590	if ( ! taxonomy_exists( $parsed_args['taxonomy'] ) ) {591		return false;592	}593 594	$show_option_all  = $parsed_args['show_option_all'];595	$show_option_none = $parsed_args['show_option_none'];596 597	$categories = get_categories( $parsed_args );598 599	$output = '';600 601	if ( $parsed_args['title_li'] && 'list' === $parsed_args['style']602		&& ( ! empty( $categories ) || ! $parsed_args['hide_title_if_empty'] )603	) {604		$output = '<li class="' . esc_attr( $parsed_args['class'] ) . '">' . $parsed_args['title_li'] . '<ul>';605	}606 607	if ( empty( $categories ) ) {608		if ( ! empty( $show_option_none ) ) {609			if ( 'list' === $parsed_args['style'] ) {610				$output .= '<li class="cat-item-none">' . $show_option_none . '</li>';611			} else {612				$output .= $show_option_none;613			}614		}615	} else {616		if ( ! empty( $show_option_all ) ) {617

History

Introduced in 4.4.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.0.4 tag, from src/wp-includes/category-template.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.