wp_dropdown_categories()

💡 云策文档标注

概述

wp_dropdown_categories() 函数用于生成或显示分类法的 HTML 下拉列表（select 元素），支持多种参数自定义输出行为，如层级显示、排序、选中项等。默认处理 'category' 分类法，但可通过参数扩展至其他分类法。

关键要点

函数核心功能是生成分类下拉列表，可通过 echo 参数控制直接输出或返回 HTML 字符串。
参数丰富，包括 show_option_all、show_option_none、hierarchical、depth、selected、taxonomy 等，用于定制列表内容和行为。
支持通过 walker 参数自定义 Walker 对象（如 Walker_CategoryDropdown）来精细控制输出结构。
包含过滤器 wp_dropdown_cats 和 list_cats，允许在输出前修改内容。
与 get_terms() 和 WP_Term_Query 紧密集成，参数可传递以扩展查询能力。

代码示例

// 基本用法：显示分类下拉列表
wp_dropdown_categories(array(
    'show_option_all' => '所有分类',
    'orderby' => 'name',
    'echo' => 1
));

// 使用 Walker 自定义输出
class Custom_Walker extends Walker_CategoryDropdown {
    // 自定义 start_el 方法
}
wp_dropdown_categories(array(
    'walker' => new Custom_Walker(),
    'taxonomy' => 'category'
));

注意事项

hierarchical 参数默认为 false，当设置为 true 时会启用层级显示，并可能覆盖 depth 参数。
hide_empty 参数控制是否包含无文章的分类，而 hide_if_empty 控制无分类时是否生成空标记。
参数 value_field 允许指定选项的 value 属性基于分类字段（如 'slug' 或 'term_id'）。
向后兼容性：已弃用 'type' => 'link' 参数，应使用 'taxonomy' => 'link_category' 替代。

📄 原文内容

Displays or retrieves the HTML dropdown list of categories.

Description

The ‘hierarchical’ argument, which is disabled by default, will override the depth argument, unless it is true. When the argument is false, it will display all of the categories. When it is enabled it will use the value in the ‘depth’ argument.

Parameters

$argsarray|stringoptional

Array or string of arguments to generate a categories drop-down element. See WP_Term_Query::__construct() for information on additional accepted arguments.

show_option_all string
Text to display for showing all categories. Default empty.
show_option_none string
Text to display for showing no categories. Default empty.
option_none_value string
Value to use when no category is selected. Default empty.
orderby string
Which column to use for ordering categories. See get_terms() for a list of accepted values. Default 'id' (term_id).
pad_counts bool
See 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
Walker object to use to build the output. Default empty which results in a Walker_CategoryDropdown instance being used.
aria_describedby string
The 'id' of an element that contains descriptive text for the select.
Default empty string.

More Arguments from get_terms( … $args )

Array or string of arguments. See WP_Term_Query::__construct() for information on accepted arguments.

Return

string HTML dropdown list of categories.

More Information

If you want to allow users to select multiple values, use wp_category_checklist().

The wp_dropdown_cats filter is applied to the output string before it is echoed/returned.

Source

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;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘list_cats’, string $element, WP_Term|null $category ): Filters a taxonomy drop-down display element.
apply_filters( ‘wp_dropdown_cats’, string $output, array $parsed_args ): Filters the taxonomy drop-down output.

Uses	Description
walk_category_dropdown_tree()`wp-includes/category-template.php`	Retrieves HTML dropdown (select) content for category list.
selected()`wp-includes/general-template.php`	Outputs the HTML selected attribute.
is_category()`wp-includes/query.php`	Determines whether the query is for an existing category archive page.
get_query_var()`wp-includes/query.php`	Retrieves the value of a query variable in the WP_Query class.
get_terms()`wp-includes/taxonomy.php`	Retrieves the terms in a given taxonomy or list of taxonomies.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
_deprecated_argument()`wp-includes/functions.php`	Marks a function argument as deprecated and inform when it has been used.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Show 5 more Show less

Used by	Description
WP_Posts_List_Table::categories_dropdown()`wp-admin/includes/class-wp-posts-list-table.php`	Displays a categories drop-down for filtering on the Posts list table.
WP_Links_List_Table::extra_tablenav()`wp-admin/includes/class-wp-links-list-table.php`
_wp_ajax_add_hierarchical_term()`wp-admin/includes/ajax-actions.php`	Handles adding a hierarchical term via AJAX.
post_categories_meta_box()`wp-admin/includes/meta-boxes.php`	Displays post categories form fields.
dropdown_cats()`wp-includes/deprecated.php`	Deprecated method for generating a drop-down of categories.
WP_Widget_Categories::widget()`wp-includes/widgets/class-wp-widget-categories.php`	Outputs the content for the current Categories widget instance.

Show 1 more Show less

Changelog

Version	Description
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.

User Contributed Notes

Skip to note 10 content

hearvox

11 years ago

This example displays a category dropdown list using JavaScript instead of a submit button, with a no-selection option (labeled: “Select category”):

<h2></h2>
	
<script type="text/javascript">
	<!--
	var dropdown = document.getElementById("cat");
	function onCatChange() {
		if ( dropdown.options[dropdown.selectedIndex].value > 0 ) {
			location.href = "<?php echo esc_url( home_url( '/' ) ); ?>?cat="+dropdown.options[dropdown.selectedIndex].value;
		}
	}
	dropdown.onchange = onCatChange;
	-->
</script>

Skip to note 11 content

hearvox

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
By default, wp_dropdown_categories only returns categories that have been assigned to at least one post. To override this set the hide_empty parameter to false ("0").
Log in to add feedback

Skip to note 12 content

hearvox

11 years ago

In this example the echo parameter (echo=0) is used. A simple preg_replace inserts the JavaScript code. It even works without JavaScript (submit button is wrapped by noscript tags).

<h2></h2>
<form id="category-select" class="category-select" action="<?php echo esc_url( home_url( '/' ) ); ?>" method="get">

	 __( 'Select category', 'textdomain' ),
		'show_count'       => 1,
		'orderby'          => 'name',
		'echo'             => 0,
	);
	?>

	
	"; ?>
	]*)>#', $replace, $select ); ?>

	

	<noscript>
		<input type="submit" value="View" />
	</noscript>

</form>

Skip to note 13 content

ayandebnath

10 years ago

You can use Walker with this wp_dropdown_categories function.

Example –

class Walker_custom_CategoryDropdown extends Walker_CategoryDropdown {

	public function start_el( &$output, $category, $depth = 0, $args = array(), $id = 0 ) {
		$pad = str_repeat(' ', $depth * 3);
 
		/** This filter is documented in wp-includes/category-template.php */
		$cat_name = apply_filters( 'list_cats', $category->name, $category );
 
		if ( isset( $args['value_field'] ) && isset( $category->{$args['value_field']} ) ) {
			$value_field = $args['value_field'];
		} else {
			$value_field = 'term_id';
		}
 
		$output .= "t<option class="level-$depth" value="" . esc_attr( $category->{$value_field} ) . """;
 
		// Type-juggling causes false matches, so we force everything to a string.
		if ( (string) $category->{$value_field} === (string) $args['selected'] )
			$output .= ' selected="selected"';
		
		$output .= ' data-uri="'.get_term_link($category).'" '; /* Custom */
		
		$output .= '>';
		$output .= $pad.$cat_name;
		if ( $args['show_count'] )
			$output .= '  ('. number_format_i18n( $category->count ) .')';
		$output .= "</option>n";
	}
}

$cat_arg=array(
	'taxonomy'=> 'category',
	'class' => 'form-control',
	'value_field' => 'term_id',
	'selected' => $taxonomy_id,
	
	'orderby' => 'name',
	'show_count' => 0,
	'hierarchical' => true,
	'hide_if_empty' => true,
	
	'walker'  => new Walker_custom_CategoryDropdown()
);

Skip to note 14 content

Lucas

4 years ago

With the following example you add a selected to the current tag archive page.

 'post_tag', 'selected'=>$tag_slug, 'show_option_none'=> 'Select an option', 'hide_empty' => 0, 'name' => 'listofoptions', 'value_field' => 'slug' ));?>
<script>
document.getElementById('listofoptions').onchange = function(){
window.location='/tag' + '/' +this.value
}
</script>

Skip to note 15 content

nsei

6 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
With the following example, when category is selected, you can automatically redirect to the category detail page.
```
<script>
  document.getElementById('cat').onchange = function(){
	// if value is category id
    if( this.value !== '-1' ){
      window.location='/?cat='+this.value
    }
  }
</script>
```
Log in to add feedback
Skip to note 16 content

markbranly

3 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

For anyone looking for the description for the pad_counts arg, it is found on the Constructor of WP_Term_Query.

Log in to add feedback
Skip to note 17 content

hearvox

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Displays a hierarchical category dropdown list in an HTML select form with a submit button, with a count of posts in each category.
```
<h2></h2>
<form id="category-select" class="category-select" action="<?php echo esc_url( home_url( '/' ) ); ?>" method="get">
	
	<input type="submit" name="submit" value="view" />
</form>
```
Log in to add feedback
Skip to note 18 content

DrLightman

3 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -2You must log in to vote on the helpfulness of this note

It’s hide_empty NOT hide_if_empty!
In the args’ Parameters list.
- Both parameters exist as valid arguments.
  
  crstauf 3 years ago
- Documentation is correct, there are 2 parameters: – hide_if_empty: to create or not the markup if there are no categories – hide_empty: to include or not categories with no posts attached
  
  GodsDeneuve 3 years ago
Log in to add feedback

云策 WordPress 开发者社区

函数文档