Help us to improve the Codex by filling out our documentation survey!Function Reference/wp dropdown categories
Languages: English • 日本語 • (Add your language)
Contents |
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' => '', '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 ); ?>
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
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: ''
- orderby
- (string) (optional) Column name to use for ordering the categories.
- 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) (optional) Category IDs to exclude. 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 ignore 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) (optional) Which category ID is selected.
- 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_counts' 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
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 action="<?php bloginfo('url'); ?>" method="get">
<div>
<?php wp_dropdown_categories('show_count=1&hierarchical=1'); ?>
<input type="submit" name="submit" value="view" />
</div>
</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 get_option('home');
?>/?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 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$1 onchange='return this.form.submit()'>", $select);
echo $select;
?>
<noscript><div><input type="submit" value="View" /></div></noscript>
</div></form>
</li>
Multiple values
If you want to allow users to select multiple values, use wp_category_checklist.
Change Log
- Since: 2.1
Source File
wp_dropdown_categories() is located in wp-includes/category-template.php.
Related
Categories: the_category(), the_category_rss(), single_cat_title(), category_description(), wp_dropdown_categories(), wp_list_categories(), get_the_category(), get_the_category_by_ID(), get_category_by_slug(), get_the_category_list(), get_category_parents(), get_category_link(), is_category(), in_category()
wp_list_authors(), wp_list_categories(), wp_list_pages(), wp_list_bookmarks(), wp_list_comments(), wp_get_archives(), wp_page_menu(), wp_dropdown_pages(), wp_dropdown_categories(), wp_dropdown_users()
