wp_list_categories() │ WP 2.1.0

Displays a list of categories as HTML links. If you click on the link, all posts from the category will be shown.

Return

null|String|false.

• If echo=1 — HTML code.
• If echo=0 — returns HTML code to the variable for further processing.

Usage template

$args = [
	'show_option_all'    => '',
	'show_option_none'   => __('No categories'),
	'orderby'            => 'name',
	'order'              => 'ASC',
	'style'              => 'list',
	'show_count'         => 0,
	'hide_empty'         => 1,
	'use_desc_for_title' => 1,
	'child_of'           => 0,
	'feed'               => '',
	'feed_type'          => '',
	'feed_image'         => '',
	'exclude'            => '',
	'exclude_tree'       => '',
	'include'            => '',
	'hierarchical'       => true,
	'title_li'           => __( 'Categories' ),
	'number'             => NULL,
	'echo'               => 1,
	'depth'              => 0,
	'current_category'   => 0,
	'pad_counts'         => 0,
	'taxonomy'           => 'category',
	'walker'             => 'Walker_Category',
	'hide_title_if_empty' => false,
	'separator'          => '<br />',
];

echo '<ul>';
	wp_list_categories( $args );
echo '</ul>';

Usage

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

Arguments passed to $args

$args is an array of arguments. It can be a string as well.

• child_of (int)
• current_category (int/array)
• depth (int)
• echo (true/false/int)
• exclude (array/string)
• exclude_tree (array/string)
• include (строка)
• hide_empty (true/false/int)
• hide_title_if_empty (true/false)
• hierarchical (true/false)
• order (string)
• orderby (string)
• separator (string)
• show_count (true/false/int)
• show_option_all (string)
• show_option_none (string)
• style (string)
• taxonomy (string)
• title_li (string)
• use_desc_for_title (true/false/int)
• number (number)
• pad_counts (true/false)
• feed (string)
• feed_image (string)
• feed_type (string)
• walker (object)

child_of(int)

Show child categories. The parameter specifies the ID of the parent category (the category whose nested categories you want to show). See get_terms().

current_category(int/array)

ID of category, or array of IDs of categories, that should get the 'current-cat' class.
Category ID or array of IDs to which you need to add the class current-cat (class="current-cat").

This is necessary to highlight the category through CSS styles. Normally, this class is added to the current category on the category page. Use this option to, for example, add this class to individual pages that are not in the current category.

Since version 4.4. you can pass an array of IDS to this parameter.

depth(int)

This parameter controls the depth of nesting of the categories to be displayed. By default 0 - show all nesting levels (all child categories).

• 0 - all nesting levels (default).
• -1 - show all child categories, but without LI lists nesting. Cancels the option hierarchical.
• 1 - show only first level categories (all types of nested categories will not be shown).
• n - number - the depth of nesting you want to show. 2 - will show the categories of the first and second level.

echo(true/false/int)

Display or return for processing.

• 1 (true) - yes, display.
• 0 (false) - no, just return the data.

Default: 1

exclude(array/string)

Exclude categories from the list. You need to specify the ID of the categories separated by comma/space.

• If this parameter is specified, the parameter child_of will be cancelled.
• If the parameter heiararchical=true, the whole branch will be excluded. If heiararchical=false, then use the exclude_tree to exclude branch.

Default: ''

exclude_tree(array/string)

Exclude the category tree from the list. Specify category IDS separated by commas. The include parameter must be empty. If the parameter heirarchical=true, use exclude instead of exclude_tree.
Default: ''

include(строка)

List only the specified categories. You need to specify the ID of the categories separated by commas.
По умолчанию: ''

hide_empty(true/false/int)

Do you want to hide categories that have no posts?

• 0 (false) - show empty (do not hide);
• 1 (true) - do not show empty categories (hide).

Default: 1

hide_title_if_empty(true/false)

Whether to hide the $title_li element if there are no terms in the list.
Default: false (title will always be shown)

hierarchical(true/false)

Show categories as a tree. Show nested (child categories) as a nested list.

• 1 (true) - tree view.
• 0 (false) - show as solid type.

Default: true

order(string)

Which direction to order categories.

• ASC - from smaller to bigger (1, 2, 3; a, b, c);
• DESC - in reverse order, from bigger to smaller (3, 2, 1; c, b, a).

Default: 'ASC'

orderby(string)

Sort the list by specific criteria. For example, by a number of posts in each category or by category name. The following criteria are available:

• ID - sort by ID;
• name - sort by name (default);
• slug - sort by slug name;
• count - by the number of posts in the category;
• term_group - by group.

Default: 'name'

separator(string)

Separator between links.
Default: '<br />'

show_count(true/false/int)

Whether to show how many posts are in the category. The number of posts will be shown after the category name in parentheses (for example, Psychology (16)).

• 1 (true) - show the number of records;
• 0 (false) - do not show the number of records.

show_option_all(string)

Text to display for showing all categories.

If you pass a non-empty string, for example, All categories, a link to all categories will be added to list (often it is a link to the blog front page). The text of the link will be the text passed to this parameter, in this case all categories.
Default: ''

show_option_none(string)

If the function does not found any categories to display, this text will be shown.
Default: 'No categories'

style(string)

The style used to display the categories list.

• list - categories will be output as an unordered list.
• none - categories will be output as a <a> tags separated by <br>.

Default: 'list'

taxonomy(string)

The name of the taxonomy to be processed.
Default: 'category'

title_li(string)

Text to use for the list title. If you change this parameter to '' (title_li=), the title will not be displayed at all.
Default: 'Categories'

use_desc_for_title(true/false/int)

Whether to insert the category description into the title attribute of the link (<a title="category Description" href="...):

• 1 (true) - Yes, insert description in title, if any;
• 0 (false) - no, do not use the description (will be: See all posts under "category name").

Default: 1

number(number)

Set the maximum number of displayed categories (SQL LIMIT). By default, no restrictions.
Default: ''

pad_counts(true/false)

Count the total number of posts in nested categories and show this number next to the parent category. Option is automatically enabled when show_counts=true and hierarchical=true.
Default: 0 (false)

feed(string)

Whether to show a link to the RSS feed (rrs-2) next to the name of the category. The text passed in this parameter will become the link text.
Default: 'Feed for all posts filed under [cat name]'

feed_image(string)

Whether to show a picture as a link to the RSS feed (rrs-2) next to the name of the category. In this parameter, you need to specify a link to the image. If this parameter is specified, the $feed parameter will be cancelled.
Default: ''

feed_type(string)

Feed type. Used to build feed link. See get_term_feed_link().
Default: '' (default feed)

walker(object)

An extension of an object (class) that is used to create a list of categories. The object passed to the parameter is an extension of the Walker_Category or Walker class.
Default: 'Walker_Category'

Examples

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

<ul>
	<?php wp_list_categories('orderby=name&show_count=1&exclude=10'); ?>
</ul>

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

<ul>
	<?php wp_list_categories('include=5,9,23&title_li=<h2>' . __('Poetry') . '</h2>' ); ?>
</ul>

<ul>
	  <?php wp_list_categories('orderby=id&show_count=1&use_desc_for_title=0&child_of=8'); ?>
</ul>

<?php
$cats = wp_list_categories('echo=0&show_count=1&title_li=<h2>Категории</h2>');
$cats = str_replace( ['(',')'], '', $cats );
echo $cats;
?>

<ul>
   <?php wp_list_categories('orderby=name&show_count=1&feed=RSS'); ?>
</ul>

<ul>
   <?php wp_list_categories('orderby=name&show_count=1&feed_image=/images/rss.gif'); ?>
</ul>

<?php
// List of categories of custom taxonomy genre

$args = array(
  'taxonomy'     => 'genre', // Name of the taxonomy
  'orderby'      => 'name',  // Sorting by name
  'show_count'   => 0,       // Don't show the number of posts
  'pad_counts'   => 0,       // Don't show the parent's number of posts
  'hierarchical' => 1,       // Tree view
  'title_li'     => ''       // Without title
);
?>

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

li.categories { ... }  /* common selector */
li.cat-item { ... }
li.cat-item-7 { ... }  /* Category with ID 7 */
li.current-cat { ... }
li.current-cat-parent { ... }
ul.children { ... }

Add Your Own Example