# wp_list_categories()
URL: https://chugunov.pro/api-wordpress/functions/wp_list_categories/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.
Тип: функция.
Появился в версии: 2.1.0.
## Сигнатура
```php
wp_list_categories( array|string $args = '' ): void|string|false
```
## Описание
Выводит или возвращает HTML-список рубрик.
## Параметры
- `$args` `array|string` — необязательный, по умолчанию `''`. Array of optional arguments. See [get_categories()](https://developer.wordpress.org/reference/functions/get_categories/) , [get_terms()](https://developer.wordpress.org/reference/functions/get_terms/) , and [WP_Term_Query::__construct()](https://developer.wordpress.org/reference/classes/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` int Category depth. Used for tab indentation. Default 0.
- `echo` bool|int Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents. Default 1.
- `exclude` int[]|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()](https://developer.wordpress.org/reference/functions/get_terms/) .
- `exclude_tree` int[]|string Array or comma/space-separated string of term IDs to exclude, along with their descendants. See [get_terms()](https://developer.wordpress.org/reference/functions/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()](https://developer.wordpress.org/reference/functions/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 `
`.
- `show_count` bool|int Whether to include post counts. Accepts 0, 1, or their bool equivalents.
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 `
` tags. Default `'list'`.
- `taxonomy` string Name of the taxonomy to retrieve. Default `'category'`.
- `title_li` string Text to use for the list title `` 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.
Accepts 0, 1, or their bool equivalents. Default 0.
- `walker` [Walker](https://developer.wordpress.org/reference/classes/walker/) [Walker](https://developer.wordpress.org/reference/classes/walker/) object to use to build the output. Default empty which results in a [Walker_Category](https://developer.wordpress.org/reference/classes/walker_category/) instance being used.
## Возвращаемое значение
`void|string|false` — 'echo' 'echo'
## Исходный код
Файл: `wp-includes/category-template.php:538`
```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' => '
',
'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 ( $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 = '' . $parsed_args['title_li'] . '';
}
if ( empty( $categories ) ) {
if ( ! empty( $show_option_none ) ) {
if ( 'list' === $parsed_args['style'] ) {
$output .= '- ' . $show_option_none . '
';
} 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 .= "- $show_option_all
";
} else {
$output .= "$show_option_all";
}
}
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 .= '
';
}
/**
* 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;
}
}
```
## История изменений
- 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.
## Связанные
Использует: [`walk_category_tree`](https://chugunov.pro/api-wordpress/functions/walk_category_tree/), [`is_category`](https://chugunov.pro/api-wordpress/functions/is_category/), [`is_tax`](https://chugunov.pro/api-wordpress/functions/is_tax/), [`is_tag`](https://chugunov.pro/api-wordpress/functions/is_tag/), [`get_queried_object`](https://chugunov.pro/api-wordpress/functions/get_queried_object/), [`get_queried_object_id`](https://chugunov.pro/api-wordpress/functions/get_queried_object_id/), [`get_categories`](https://chugunov.pro/api-wordpress/functions/get_categories/), [`wp_parse_id_list`](https://chugunov.pro/api-wordpress/functions/wp_parse_id_list/), [`taxonomy_exists`](https://chugunov.pro/api-wordpress/functions/taxonomy_exists/), [`get_post_type_archive_link`](https://chugunov.pro/api-wordpress/functions/get_post_type_archive_link/), [`__`](https://chugunov.pro/api-wordpress/functions/__/), [`esc_attr`](https://chugunov.pro/api-wordpress/functions/esc_attr/), [`esc_url`](https://chugunov.pro/api-wordpress/functions/esc_url/), [`wp_parse_args`](https://chugunov.pro/api-wordpress/functions/wp_parse_args/), [`get_taxonomy`](https://chugunov.pro/api-wordpress/functions/get_taxonomy/), [`home_url`](https://chugunov.pro/api-wordpress/functions/home_url/), [`get_permalink`](https://chugunov.pro/api-wordpress/functions/get_permalink/), [`apply_filters`](https://chugunov.pro/api-wordpress/functions/apply_filters/), [`get_option`](https://chugunov.pro/api-wordpress/functions/get_option/), [`get_post_type_object`](https://chugunov.pro/api-wordpress/functions/get_post_type_object/).
Используется в: [`wp_list_cats`](https://chugunov.pro/api-wordpress/functions/wp_list_cats/), `WP_Widget_Categories::widget`.
Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/wp_list_categories/