Languages:
English •
日本語
(Add your language)
Description
Display or retrieve the HTML dropdown list of categories.
Usage
<?php wp_dropdown_categories( $args ); ?>
Default Usage
<?php $args = array(
'show_option_all' => '',
'show_option_none' => '',
'option_none_value' => '-1',
'orderby' => 'ID',
'order' => 'ASC',
'show_count' => 0,
'hide_empty' => 1,
'child_of' => 0,
'exclude' => '',
'include' => '',
'echo' => 1,
'selected' => 0,
'hierarchical' => 0,
'name' => 'cat',
'id' => '',
'class' => 'postform',
'depth' => 0,
'tab_index' => 0,
'taxonomy' => 'category',
'hide_if_empty' => false,
'value_field' => 'term_id',
); ?>
By default, the usage shows:
- Sorts by category id in ascending order
- Does not show the count of posts within a category
- Does not show 'empty' categories
- Excludes nothing
- Displays (echos) the categories
- No category is 'selected' in the form
- Does not display the categories in a hierarchical structure
- Assigns 'cat' to the form name
- Assigns the form to the class 'postform'
- No select ID so will default to 'name'
- Class of postform
- No depth limit
- Tab index of 0
- Use taxonomy = category
- Hide dropdown if no terms returned
- Outputs the term ID upon selecting the dropdown option
Parameters
- $args
- (string|array) (optional) Override default arguments. See Notes.
- Default:
Return Values
- (string)
- HTML content only if 'echo' argument is 0.
Arguments
- show_option_all
- (string) (optional) Text to display for showing an 'all categories' option. Default will not show an option to select 'all categories'.
- Default: ''
- show_option_none
- (string) (optional) Text to display for showing a 'no categories' option. Default will not show an option to select 'no categories'.
- Default: ''
- option_none_value
- (string) (optional) Value for 'no categories' option.
- Default: -1
- orderby
- (string) (optional) Column name to use for ordering the categories. See get_terms() for valid values.'
- Default: 'ID'
- order
- (string) (optional) Direction to sort categories. Valid values are 'ASC' and 'DESC'.
- Default: 'ASC'
- show_count
- (boolean) (optional) Show (1/True) or hide (0/False) post count in category.
- Default: 0/False
- hide_empty
- (boolean) (optional) Show (0/False) or hide (1/True) category with no posts.
- Default: 1/True
- child_of
- (integer) (optional) Display all categories that are descendants (i.e. children & grandchildren) of the category identified by its ID. See get_categories().
- Default: 0/False
- exclude
- (string array) (optional) Category IDs to exclude. See get_categories().
- Default: ''
- include
- (string array) (optional) Category IDs to include. See get_categories().
- Default: ''
- exclude_tree
- (string) (required) optional
- Default: None
- echo
- (boolean) (optional) Send output to browser (1/True) or return output to PHP (0/False)
- Default: 1/True
- depth
- (integer) (optional) The max depth. This is ignored unless hierarchical is set to true.
- Default: 0/False
- tab_index
- (integer) (optional) The 'tabindex' attribute for the select element.
- Default: 0/False
- name
- (string) (optional) The 'name' attribute value for select element.
- Default: 'cat'
- id
- (string) (optional) The 'id' attribute value for select element.
- Default: 'name'
- class
- (string) (optional) The 'class' attribute value for select element.
- Default: 'postform'
- selected
- (integer|string) (optional) Which category ID is initially selected in the dropdown. The type of value should match the 'value_field', which is term_id by default. For example, if 'value_field' is set to "slug", then 'selected' will take a slug instead of an ID.
- Default: 0/False
- hierarchical
- (boolean) (optional) Display all categories (0/False) or display categories (1/True) to a depth of 'depth'.
- Default: 0/False
- pad_counts
- (boolean) (optional) Calculates link or post counts by including items from child categories. If 'show_count' and 'hierarchical' are true this is automatically set to true.
- Default: 0/False
- taxonomy
- (string) (optional) Taxonomy to return. Valid values are 'category', 'post_tag' or any registered taxonomy.
- Default: category
- hide_if_empty
- (boolean) (optional) Hide dropdown (1/True) or show (0/False) if no terms returned.
- Default: 0/False
- value_field
- (string) (optional) 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
Examples
Dropdown with Submit Button
Displays a hierarchical category dropdown list in HTML form with a submit button, in a WordPress sidebar unordered list, with a count of posts in each category.
<li id="categories">
<h2><?php _e( 'Categories:' ); ?></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>
</li>
Dropdown without a Submit Button using JavaScript
Example depicts using the show_option_none parameter and was gleaned from Moshu's forum post.
<li id="categories"><h2><?php _e( 'Posts by Category' ); ?></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>
</li>
Dropdown without a Submit Button using JavaScript (2)
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).
<li id="categories">
<h2><?php _e( 'Posts by Category' ); ?></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' ),
'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>
</li>
Troubleshooting
Empty dropdown
By default, wp_dropdown_categories will only return categories that have been attached to at least one post. If you would like to override this functionality, you need to set the hide_empty parameter to false ("0").
Example:
<?php wp_dropdown_categories( 'hide_empty=0' ); ?>
Dropdown with all values selected
The default value for the selected parameter is 0, but this can cause a dropdown with all terms marked as selected. To fix this, set the selected parameter to false, rather than 0.
Example:
<?php wp_dropdown_categories( 'selected=false' ); ?>
Notes
Change Log
Source File
wp_dropdown_categories() is located in wp-includes/category-template.php.
Related
List & Dropdown Functions