# wp_dropdown_categories()

URL: https://chugunov.pro/api-wordpress/functions/wp_dropdown_categories/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 6.1.0.

## Сигнатура

```php
wp_dropdown_categories( array|string $args = '' ): string
```

## Описание

Аргумент «hierarchical», отключённый по умолчанию, переопределяет аргумент depth, если только он не равен true. Когда аргумент равен false, отображаются все рубрики. Когда он включён, используется значение аргумента «depth».

## Параметры

- `$args` `array|string` — необязательный, по умолчанию `''`. Array or string of arguments to generate a categories drop-down element. See [WP_Term_Query::__construct()](https://developer.wordpress.org/reference/classes/wp_term_query/__construct/) for information on additional accepted arguments.
  
  - `show_option_all` string Text to display for showing all categories.
  
  - `show_option_none` string Text to display for showing no categories.
  
  - `option_none_value` string Value to use when no category is selected.
  
  - `orderby` string Which column to use for ordering categories. See [get_terms()](https://developer.wordpress.org/reference/functions/get_terms/) for a list of accepted values. Default `'id'` (term_id).
  
  - `pad_counts` bool See [get_terms()](https://developer.wordpress.org/reference/functions/get_terms/) for an argument description. Default false.
  
  - `show_count` bool|int Whether to include post counts. Accepts 0, 1, or their bool equivalents.
  
  Default 0.
  
  - `echo` bool|int Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents. Default 1.
  
  - `hierarchical` bool|int Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool equivalents. Default 0.
  
  - `depth` int Maximum depth. Default 0.
  
  - `tab_index` int Tab index for the select element. Default 0 (no tabindex).
  
  - `name` string Value for the `'name'` attribute of the select element. Default `'cat'`.
  
  - `id` string Value for the `'id'` attribute of the select element. Defaults to the value of `$name`.
  
  - `class` string Value for the `'class'` attribute of the select element. Default `'postform'`.
  
  - `selected` int|string Value of the option that should be selected. Default 0.
  
  - `value_field` string Term field that should be used to populate the `'value'` attribute of the option elements. Accepts any valid term field: `'term_id'`, `'name'`, `'slug'`, `'term_group'`, `'term_taxonomy_id'`, `'taxonomy'`, `'description'`, `'parent'`, `'count'`. Default `'term_id'`.
  
  - `taxonomy` string|array Name of the taxonomy or taxonomies to retrieve. Default `'category'`.
  
  - `hide_if_empty` bool True to skip generating markup if no categories are found.
  
  Default false (create select element even if no categories are found).
  
  - `required` bool Whether the `<select>` element should have the HTML5 `'required'` attribute.
  
  Default false.
  
  - `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_CategoryDropdown](https://developer.wordpress.org/reference/classes/walker_categorydropdown/) instance being used.
  
  - `aria_describedby` string The `'id'` of an element that contains descriptive text for the select.

## Возвращаемое значение

`string`

## Исходный код

Файл: `wp-includes/category-template.php:344`

```php
function wp_dropdown_categories( $args = '' ) {
	$defaults = array(
		'show_option_all'   => '',
		'show_option_none'  => '',
		'orderby'           => 'id',
		'order'             => 'ASC',
		'show_count'        => 0,
		'hide_empty'        => 1,
		'child_of'          => 0,
		'exclude'           => '',
		'echo'              => 1,
		'selected'          => 0,
		'hierarchical'      => 0,
		'name'              => 'cat',
		'id'                => '',
		'class'             => 'postform',
		'depth'             => 0,
		'tab_index'         => 0,
		'taxonomy'          => 'category',
		'hide_if_empty'     => false,
		'option_none_value' => -1,
		'value_field'       => 'term_id',
		'required'          => false,
		'aria_describedby'  => '',
	);

	$defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0;

	// Back compat.
	if ( isset( $args['type'] ) && 'link' === $args['type'] ) {
		_deprecated_argument(
			__FUNCTION__,
			'3.0.0',
			sprintf(
				/* translators: 1: "type => link", 2: "taxonomy => link_category" */
				__( '%1$s is deprecated. Use %2$s instead.' ),
				'<code>type => link</code>',
				'<code>taxonomy => link_category</code>'
			)
		);
		$args['taxonomy'] = 'link_category';
	}

	// Parse incoming $args into an array and merge it with $defaults.
	$parsed_args = wp_parse_args( $args, $defaults );

	$option_none_value = $parsed_args['option_none_value'];

	if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) {
		$parsed_args['pad_counts'] = true;
	}

	$tab_index = $parsed_args['tab_index'];

	$tab_index_attribute = '';
	if ( (int) $tab_index > 0 ) {
		$tab_index_attribute = " tabindex=\"$tab_index\"";
	}

	// Avoid clashes with the 'name' param of get_terms().
	$get_terms_args = $parsed_args;
	unset( $get_terms_args['name'] );
	$categories = get_terms( $get_terms_args );

	$name     = esc_attr( $parsed_args['name'] );
	$class    = esc_attr( $parsed_args['class'] );
	$id       = $parsed_args['id'] ? esc_attr( $parsed_args['id'] ) : $name;
	$required = $parsed_args['required'] ? 'required' : '';

	$aria_describedby_attribute = $parsed_args['aria_describedby'] ? ' aria-describedby="' . esc_attr( $parsed_args['aria_describedby'] ) . '"' : '';

	if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) {
		$output = "<select $required name='$name' id='$id' class='$class'$tab_index_attribute$aria_describedby_attribute>\n";
	} else {
		$output = '';
	}
	if ( empty( $categories ) && ! $parsed_args['hide_if_empty'] && ! empty( $parsed_args['show_option_none'] ) ) {

		/**
		 * Filters a taxonomy drop-down display element.
		 *
		 * A variety of taxonomy drop-down display elements can be modified
		 * just prior to display via this filter. Filterable arguments include
		 * 'show_option_none', 'show_option_all', and various forms of the
		 * term name.
		 *
		 * @since 1.2.0
		 *
		 * @see wp_dropdown_categories()
		 *
		 * @param string       $element  Category name.
		 * @param WP_Term|null $category The category object, or null if there's no corresponding category.
		 */
		$show_option_none = apply_filters( 'list_cats', $parsed_args['show_option_none'], null );
		$output          .= "\t<option value='" . esc_attr( $option_none_value ) . "' selected='selected'>$show_option_none</option>\n";
	}

	if ( ! empty( $categories ) ) {

		if ( $parsed_args['show_option_all'] ) {

			/** This filter is documented in wp-includes/category-template.php */
			$show_option_all = apply_filters( 'list_cats', $parsed_args['show_option_all'], null );
			$selected        = ( '0' === (string) $parsed_args['selected'] ) ? " selected='selected'" : '';
			$output         .= "\t<option value='0'$selected>$show_option_all</option>\n";
		}

		if ( $parsed_args['show_option_none'] ) {

			/** This filter is documented in wp-includes/category-template.php */
			$show_option_none = apply_filters( 'list_cats', $parsed_args['show_option_none'], null );
			$selected         = selected( $option_none_value, $parsed_args['selected'], false );
			$output          .= "\t<option value='" . esc_attr( $option_none_value ) . "'$selected>$show_option_none</option>\n";
		}

		if ( $parsed_args['hierarchical'] ) {
			$depth = $parsed_args['depth'];  // Walk the full depth.
		} else {
			$depth = -1; // Flat.
		}
		$output .= walk_category_dropdown_tree( $categories, $depth, $parsed_args );
	}

	if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) {
		$output .= "</select>\n";
	}

	/**
	 * Filters the taxonomy drop-down output.
	 *
	 * @since 2.1.0
	 *
	 * @param string $output      HTML output.
	 * @param array  $parsed_args Arguments used to build the drop-down.
	 */
	$output = apply_filters( 'wp_dropdown_cats', $output, $parsed_args );

	if ( $parsed_args['echo'] ) {
		echo $output;
	}

	return $output;
}
```

## История изменений

- 6.1.0 — Introduced the aria_describedby argument.
- 4.6.0 — Introduced the required argument.
- 4.2.0 — Introduced the value_field argument.
- 2.1.0 — Introduced.

## Связанные

Использует: [`walk_category_dropdown_tree`](https://chugunov.pro/api-wordpress/functions/walk_category_dropdown_tree/), [`selected`](https://chugunov.pro/api-wordpress/functions/selected/), [`is_category`](https://chugunov.pro/api-wordpress/functions/is_category/), [`get_query_var`](https://chugunov.pro/api-wordpress/functions/get_query_var/), `WP_Query`, [`get_terms`](https://chugunov.pro/api-wordpress/functions/get_terms/), [`__`](https://chugunov.pro/api-wordpress/functions/__/), [`esc_attr`](https://chugunov.pro/api-wordpress/functions/esc_attr/), [`_deprecated_argument`](https://chugunov.pro/api-wordpress/functions/_deprecated_argument/), [`wp_parse_args`](https://chugunov.pro/api-wordpress/functions/wp_parse_args/), [`apply_filters`](https://chugunov.pro/api-wordpress/functions/apply_filters/).
Используется в: `WP_Posts_List_Table::categories_dropdown`, `WP_Links_List_Table::extra_tablenav`, [`_wp_ajax_add_hierarchical_term`](https://chugunov.pro/api-wordpress/functions/_wp_ajax_add_hierarchical_term/), [`post_categories_meta_box`](https://chugunov.pro/api-wordpress/functions/post_categories_meta_box/), [`dropdown_cats`](https://chugunov.pro/api-wordpress/functions/dropdown_cats/), `WP_Widget_Categories::widget`.

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/wp_dropdown_categories/