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

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

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 value

void|string|false

Void if 'echo' argument is true, HTML list of categories if 'echo' is false.
False if the taxonomy does not exist.

Performance profile

How much work a call to wp_list_categories() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_terms().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

82–160

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 259.

Plugin surface

1 hook

Third-party callbacks on 'wp_list_categories' run inside this call, and their cost is not bounded by anything here.

Called by

3

3 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• optionoption read or writeget_option()called directly
• hookthird-party callbacksapply_filters()called directly
• querycontent queryget_terms()one call below wp_list_categories()
• cacheobject cachewp_cache_get()one call below wp_list_categories()
• serializeserialisationmaybe_unserialize()one call below wp_list_categories()

Further down the call graph this can also reach transient. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 40 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_list_categories() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters 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 code

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

Changelog

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.1.0 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.