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.

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.
  • 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 get_terms( … $args )Array or string of arguments. See WP_Term_Query::__construct() for information on accepted arguments.

Default:''

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

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.

Changelog

VersionDescription
6.1.0Introduced the aria_describedby argument.
4.6.0Introduced the required argument.
4.2.0Introduced the value_field argument.
2.1.0Introduced.

User Contributed Notes

  1. Skip to note 10 content

    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 12 content

    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>
  3. Skip to note 13 content

    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()
    );
  4. Skip to note 14 content

    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 15 content

    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 16 content

    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>
  7. Skip to note 18 content

    It’s hide_empty NOT hide_if_empty!
    In the args’ Parameters list.

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