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

Description

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.Default: ''

• $show_option_allstringdefault: empty

  Text to display for showing all categories.

• $show_option_nonestringdefault: empty

  Text to display for showing no categories.

• $option_none_valuestringdefault: empty

  Value to use when no category is selected.

• $orderbystringdefault: 'id' (term_id)

  Which column to use for ordering categories. See get_terms() for a list of accepted values.

• $pad_countsbooldefault: false

  See get_terms() for an argument description.

• $show_countbool|intdefault: 0

  Whether to include post counts. Accepts 0, 1, or their bool equivalents.

• $echobool|intdefault: 1

  Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents.

• $hierarchicalbool|intdefault: 0

  Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool equivalents.

• $depthintdefault: 0

  Maximum depth.

• $tab_indexintdefault: 0 (no tabindex)

  Tab index for the select element.

• $namestringdefault: 'cat'

  Value for the 'name' attribute of the select element.

• $idstring

  Value for the 'id' attribute of the select element. Defaults to the value of $name.

• $classstringdefault: 'postform'

  Value for the 'class' attribute of the select element.

• $selectedint|stringdefault: 0

  Value of the option that should be selected.

• $value_fieldstringdefault: 'term_id'

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

• $taxonomystring|arraydefault: 'category'

  Name of the taxonomy or taxonomies to retrieve.

• $hide_if_emptybooldefault: false (create select element even if no categories are found)

  True to skip generating markup if no categories are found.

• $requiredbooldefault: false

  Whether the <select> element should have the HTML5 'required' attribute.

• $walkerWalkerdefault: empty which results in a Walker_CategoryDropdown instance being used

  Walker object to use to build the output.

• $aria_describedbystringdefault: empty string

  The 'id' of an element that contains descriptive text for the select.

Return

string

HTML dropdown list of categories.

Hooks fired · 4

4 hooks fire while wp_dropdown_categories() runs, in this order:

1. 1
   apply_filters( list_cats )filterline 437 (+93 into the body)

   Filters a taxonomy drop-down display element.

2. 2
   apply_filters( list_cats )filterline 446 (+102 into the body)

   Filters a taxonomy drop-down display element.

3. 3
   apply_filters( list_cats )filterline 454 (+110 into the body)

   Filters a taxonomy drop-down display element.

4. 4
   apply_filters( wp_dropdown_cats )filterline 479 (+135 into the body)

   Filters the taxonomy drop-down output.

Uses · 10

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

Used by · 7

• WP_Links_List_Table::extra_tablenav()
• WP_Posts_List_Table::categories_dropdown()Displays a categories drop-down for filtering on the Posts list table.
• WP_Widget_Categories::widget()Outputs the content for the current Categories widget instance.
• _wp_ajax_add_hierarchical_term()Handles adding a hierarchical term via AJAX.
• dropdown_cats()Deprecated method for generating a drop-down of categories.
• post_categories_meta_box()Displays post categories form fields.
• render_block_core_categories()Renders the `core/categories` block on server.

Source

View on Trac ↗View on GitHub ↗

344function wp_dropdown_categories( $args = '' ) {345	$defaults = array(346		'show_option_all'   => '',347		'show_option_none'  => '',348		'orderby'           => 'id',349		'order'             => 'ASC',350		'show_count'        => 0,351		'hide_empty'        => 1,352		'child_of'          => 0,353		'exclude'           => '',354		'echo'              => 1,355		'selected'          => 0,356		'hierarchical'      => 0,357		'name'              => 'cat',358		'id'                => '',359		'class'             => 'postform',360		'depth'             => 0,361		'tab_index'         => 0,362		'taxonomy'          => 'category',363		'hide_if_empty'     => false,364		'option_none_value' => -1,365		'value_field'       => 'term_id',366		'required'          => false,367		'aria_describedby'  => '',368	);369 370	$defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0;371 372	// Back compat.373	if ( isset( $args['type'] ) && 'link' === $args['type'] ) {374		_deprecated_argument(375			__FUNCTION__,376			'3.0.0',377			sprintf(378				/* translators: 1: "type => link", 2: "taxonomy => link_category" */379				__( '%1$s is deprecated. Use %2$s instead.' ),380				'<code>type => link</code>',381				'<code>taxonomy => link_category</code>'382			)383		);384		$args['taxonomy'] = 'link_category';385	}386 387	// Parse incoming $args into an array and merge it with $defaults.388	$parsed_args = wp_parse_args( $args, $defaults );389 390	$option_none_value = $parsed_args['option_none_value'];391 392	if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) {393		$parsed_args['pad_counts'] = true;394	}395 396	$tab_index = $parsed_args['tab_index'];397 398	$tab_index_attribute = '';399	if ( (int) $tab_index > 0 ) {400		$tab_index_attribute = " tabindex=\"$tab_index\"";401	}402 403	// Avoid clashes with the 'name' param of get_terms().404	$get_terms_args = $parsed_args;405	unset( $get_terms_args['name'] );406	$categories = get_terms( $get_terms_args );407 408	$name     = esc_attr( $parsed_args['name'] );409	$class    = esc_attr( $parsed_args['class'] );410	$id       = $parsed_args['id'] ? esc_attr( $parsed_args['id'] ) : $name;411	$required = $parsed_args['required'] ? 'required' : '';412 413	$aria_describedby_attribute = $parsed_args['aria_describedby'] ? ' aria-describedby="' . esc_attr( $parsed_args['aria_describedby'] ) . '"' : '';414 415	if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) {416		$output = "<select $required name='$name' id='$id' class='$class'$tab_index_attribute$aria_describedby_attribute>\n";417	} else {418		$output = '';419	}420	if ( empty( $categories ) && ! $parsed_args['hide_if_empty'] && ! empty( $parsed_args['show_option_none'] ) ) {421 422		/**423		 * Filters a taxonomy drop-down display element.

History

Introduced in 6.1.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 6.7.7 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.