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

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.


Top ↑

Parameters

$args array|string Optional
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.
  • 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() 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.
More Arguments from WP_Term_Query::__construct( ... $query ) Array or query string of term query parameters.
  • taxonomy string|string[]
    Taxonomy name, or array of taxonomy names, to which results should be limited.
  • object_ids int|int[]
    Object ID, or array of object IDs. Results will be limited to terms associated with these objects.
  • orderby string
    Field(s) to order terms by. Accepts:
    • Term fields ('name', 'slug', 'term_group', 'term_id', 'id', 'description', 'parent', 'term_order'). Unless $object_ids is not empty, 'term_order' is treated the same as 'term_id'.
    • 'count' to use the number of objects associated with the term.
    • 'include' to match the 'order' of the $include param.
    • 'slug__in' to match the 'order' of the $slug param.
    • 'meta_value'
    • 'meta_value_num'.
    • The value of $meta_key.
    • The array keys of $meta_query.
    • 'none' to omit the ORDER BY clause.
    Default 'name'.
  • order string
    Whether to order terms in ascending or descending order.
    Accepts 'ASC' (ascending) or 'DESC' (descending).
    Default 'ASC'.
  • hide_empty bool|int
    Whether to hide terms not assigned to any posts. Accepts 1|true or 0|false. Default 1|true.
  • include int[]|string
    Array or comma/space-separated string of term IDs to include.
    Default empty array.
  • exclude int[]|string
    Array or comma/space-separated string of term IDs to exclude.
    If $include is non-empty, $exclude is ignored.
    Default empty array.
  • exclude_tree int[]|string
    Array or comma/space-separated string of term IDs to exclude along with all of their descendant terms. If $include is non-empty, $exclude_tree is ignored. Default empty array.
  • number int|string
    Maximum number of terms to return. Accepts ''|0 (all) or any positive number. Default ''|0 (all). Note that $number may not return accurate results when coupled with $object_ids.
    See #41796 for details.
  • offset int
    The number by which to offset the terms query.
  • fields string
    Term fields to query for. Accepts:
    • 'all' Returns an array of complete term objects (WP_Term[]).
    • 'all_with_object_id' Returns an array of term objects with the 'object_id' param (WP_Term[]). Works only when the $object_ids parameter is populated.
    • 'ids' Returns an array of term IDs (int[]).
    • 'tt_ids' Returns an array of term taxonomy IDs (int[]).
    • 'names' Returns an array of term names (string[]).
    • 'slugs' Returns an array of term slugs (string[]).
    • 'count' Returns the number of matching terms (int).
    • 'id=>parent' Returns an associative array of parent term IDs, keyed by term ID (int[]).
    • 'id=>name' Returns an associative array of term names, keyed by term ID (string[]).
    • 'id=>slug' Returns an associative array of term slugs, keyed by term ID (string[]).
    Default 'all'.
  • count bool
    Whether to return a term count. If true, will take precedence over $fields. Default false.
  • name string|string[]
    Name or array of names to return term(s) for.
  • slug string|string[]
    Slug or array of slugs to return term(s) for.
  • term_taxonomy_id int|int[]
    Term taxonomy ID, or array of term taxonomy IDs, to match when querying terms.
  • hierarchical bool
    Whether to include terms that have non-empty descendants (even if $hide_empty is set to true). Default true.
  • search string
    Search criteria to match terms. Will be SQL-formatted with wildcards before and after.
  • name__like string
    Retrieve terms with criteria by which a term is LIKE $name__like.
  • description__like string
    Retrieve terms where the description is LIKE $description__like.
  • pad_counts bool
    Whether to pad the quantity of a term's children in the quantity of each term's "count" object variable. Default false.
  • get string
    Whether to return terms regardless of ancestry or whether the terms are empty. Accepts 'all' or '' (disabled). Default ''.
  • child_of int
    Term ID to retrieve child terms of. If multiple taxonomies are passed, $child_of is ignored. Default 0.
  • parent int
    Parent term ID to retrieve direct-child terms of.
  • childless bool
    True to limit results to terms that have no children.
    This parameter has no effect on non-hierarchical taxonomies.
    Default false.
  • cache_domain string
    Unique cache key to be produced when this query is stored in an object cache. Default 'core'.
  • update_term_meta_cache bool
    Whether to prime meta caches for matched terms. Default true.
  • meta_key string|string[]
    Meta key or keys to filter by.
  • meta_value string|string[]
    Meta value or values to filter by.
  • meta_compare string
    MySQL operator used for comparing the meta value.
    See WP_Meta_Query::__construct() for accepted values and default value.
  • meta_compare_key string
    MySQL operator used for comparing the meta key.
    See WP_Meta_Query::__construct() for accepted values and default value.
  • meta_type string
    MySQL data type that the meta_value column will be CAST to for comparisons.
    See WP_Meta_Query::__construct() for accepted values and default value.
  • meta_type_key string
    MySQL data type that the meta_key column will be CAST to for comparisons.
    See WP_Meta_Query::__construct() for accepted values and default value.
  • meta_query array
    An associative array of WP_Meta_Query arguments.
    See WP_Meta_Query::__construct() for accepted values.

Default: ''


Top ↑

Return

string HTML dropdown list of categories.


Top ↑

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.


Top ↑

Source

File: wp-includes/category-template.php. View all references

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

Top ↑

Hooks



Top ↑

Changelog

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.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    Contributed by hearvox

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

    <h2><?php _e( 'Posts by Category', 'textdomain' ); ?></h2>
    	<?php wp_dropdown_categories( 'show_option_none=Select category' ); ?>
    <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>
  2. Skip to note 3 content
    Contributed by ayandebnath

    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('&nbsp;', $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 .= '&nbsp;&nbsp;('. 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()
    );
  3. Skip to note 4 content
    Contributed by hearvox

    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><?php _e( 'Posts by Category', 'textdomain' ); ?></h2>
    <form id="category-select" class="category-select" action="<?php echo esc_url( home_url( '/' ) ); ?>" method="get">
    
    	<?php
    	$args = array(
    		'show_option_none' => __( 'Select category', 'textdomain' ),
    		'show_count'       => 1,
    		'orderby'          => 'name',
    		'echo'             => 0,
    	);
    	?>
    
    	<?php $select  = wp_dropdown_categories( $args ); ?>
    	<?php $replace = "<select$1 onchange='return this.form.submit()'>"; ?>
    	<?php $select  = preg_replace( '#<select([^>]*)>#', $replace, $select ); ?>
    
    	<?php echo $select; ?>
    
    	<noscript>
    		<input type="submit" value="View" />
    	</noscript>
    
    </form>
  4. Skip to note 5 content
    Contributed by nsei

    With the following example, when category is selected, you can automatically redirect to the category detail page.

    <?php wp_dropdown_categories(); ?>
    
    <script>
      document.getElementById('cat').onchange = function(){
    	// if value is category id
        if( this.value !== '-1' ){
          window.location='/?cat='+this.value
        }
      }
    </script>
  5. Skip to note 6 content
    Contributed by Lucas

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

    <?php
    $tag_slug = get_query_var( 'tag' );
    wp_dropdown_categories(array('taxonomy'=> '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>
  6. Skip to note 7 content
    Contributed by hearvox

    Displays a hierarchical category dropdown list in an HTML select form with a submit button, with a count of posts in each category.

    <h2><?php _e( 'Categories:', 'textdomain' ); ?></h2>
    <form id="category-select" class="category-select" action="<?php echo esc_url( home_url( '/' ) ); ?>" method="get">
    	<?php wp_dropdown_categories( 'show_count=1&hierarchical=1' ); ?>
    	<input type="submit" name="submit" value="view" />
    </form>

You must log in before being able to contribute a note or feedback.