wp_dropdown_categories()
Display or retrieve the HTML dropdown list of categories. Instead of categories you can specify the name of an custom taxonomy.
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.
Hooks from the function
Return
String. HTML code of the category drop-down list (<select>).
Usage Template
$args = array( 'show_option_all' => '', 'show_option_none' => '', 'option_none_value' => -1, 'orderby' => 'ID', 'order' => 'ASC', 'show_last_update' => 0, 'show_count' => 0, 'hide_empty' => 1, 'child_of' => 0, 'exclude' => '', 'echo' => 1, 'selected' => 0, 'hierarchical' => 0, 'name' => 'cat', 'id' => 'name', 'class' => 'postform', 'depth' => 0, 'tab_index' => 0, 'taxonomy' => 'category', 'hide_if_empty' => false, 'value_field' => 'term_id', // field to set as option value 'required' => false, ); wp_dropdown_categories( $args );
Usage
wp_dropdown_categories( $args );
In addition to following parameters, you can also specify any from get_terms().
- $args(array|string)
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_all(string)
Text to display for showing all categories.
Default: '' -
show_option_none(string)
Text to display for showing no categories.
Default: '' -
option_none_value(string)
Value to use when no category is selected.
Default: '' -
orderby(string)
Which column to use for ordering categories. See get_terms() for a list of accepted values. (term_id).
Default: 'id' -
pad_counts(true|false)
See get_terms() for an argument description.
Default: false -
show_count(true|false|int)
Whether to include post counts. Accepts 0, 1, or their bool equivalents. -
echo(true|false|int)
Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents.
Default: 1 -
hierarchical(true|false|int)
Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool equivalents. -
depth(int)
Maximum depth. -
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.
Default: 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. -
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(true|false)
True to skip generating markup if no categories are found.
Default: false (create select element even if no categories are found) -
required(true|false)
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
-
Examples
#1 Dropdown list with Submit button
Example output of category dropdown list with Submit button:
<h2>Categories:</h2>
<form action="<?php bloginfo('url'); ?>" method="get">
<?php wp_dropdown_categories('show_count=1&hierarchical=1'); ?>
<input type="submit" name="submit" value="view"/>
</form> #2 Javascript dropdown list (no Submitt button)
An example showing the use of the show_option_none argument:
<h2>Categories:</h2>
<?php wp_dropdown_categories('show_option_none=Select categories'); ?>
<script>
var dropdown = document.getElementById("cat");
function onCatChange() {
if ( dropdown.options[dropdown.selectedIndex].value > 0 ) {
location.href = "<?php echo get_option('home');
?>/?cat="+dropdown.options[dropdown.selectedIndex].value;
}
}
dropdown.onchange = onCatChange;
</script> #3 Dropdown list using Javascript (2) (no Submit button)
<h2><?php _e('Posts by Category'); ?></h2>
<form action="<?php bloginfo('url'); ?>/" method="get">
<div>
<?php
$select = wp_dropdown_categories('show_option_none=Select category&show_count=1&orderby=name&echo=0');
$select = preg_replace("#<select([^>]*)>#", "<select onchange='return this.form.submit()'>", $select);
echo $select;
?>
<noscript><div><input type="submit" value="View" /></div></noscript>
</div>
</form>
#4 Add the multiple parameter
// This filter allow a wp_dropdown_categories select to return multiple items
add_filter( 'wp_dropdown_cats', 'willy_wp_dropdown_cats_multiple', 10, 2 );
function willy_wp_dropdown_cats_multiple( $output, $r ) {
if ( ! empty( $r['multiple'] ) ) {
$output = preg_replace('/<select(.*?)>/i', '<select multiple="multiple">', $output );
$output = preg_replace('/name=([\"]{1})(.*?)/i', 'name=[]', $output );
}
return $output;
}
Now we use a function with the multiple parameter
wp_dropdown_categories( [ 'taxonomy' => 'category', 'multiple' => true, 'selected' => '10, 12', // selected terms 'hide_empty' => false, ] );
We get:
Original code found here.
Changelog
| Since 2.1.0 | Introduced. |
| Since 4.2.0 | Introduced the value_field argument. |
| Since 4.6.0 | Introduced the required argument. |
| Since 6.1.0 | Introduced the aria_describedby argument. |