WordPress.org

Template Tags/wp dropdown categories

Languages: English • 日本語 • (Add your language)

Description

Displays a list of categories in a select (i.e dropdown) box with no submit button.

Usage

<?php wp_dropdown_categories( $args ); ?>

Default Usage

<?php $args = array( 'show_option_all' => , 'show_option_none' => , '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', 'class' => 'postform', 'depth' => 0 ); ?>

By default, the usage shows:

Sorts by category id in ascending order
Does not show the last date updated
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 depth limit

Parameters

show_option_all: (string) Causes the HTML for the dropdown to allow you to select All of the categories.

show_option_none: (string) Causes the HTML for the dropdown to allow you to select NONE of the categories.

orderby

(string) Key to sort options by. Valid values:

'ID' (Default)
'name'

order

(string) Sort order for options. Valid values:

'ASC' (Default)
'DESC'

show_last_update

(boolean) Sets whether to display the date of the last post in each category. Valid values:

1 (True)
0 (False - Default)

show_count

(boolean) Sets whether to display a count of posts in each category. Valid values:

1 (True)
0 (False - Default)

hide_empty

(boolean) Sets whether to hide (not display) categories with no posts. Valid values:

1 (True - Default)
0 (False)

child_of: (integer) Only display categories that are children of the category identified by its ID. There is no default for this parameter.

exclude: (string) Comma separated list of category IDs to exclude. For example, 'exclude=4,12' means category IDs 4 and 12 will NOT be displayed/echoed or returned. Defaults to exclude nothing.

exclude_tree (string): Define a comma-separated list of "parent" category IDs to be excluded. Use this parameter to exclude a parent and all of that parent's child categories. So 'exclude_tree=5' would exclude the parent category 5, and its child (all descendant) categories. If hierarchical is true, exclude_tree uses the exclude value. This parameter was available at Version 2.7.1.

echo

(boolean) Display bookmarks (TRUE) or return them for use by PHP (FALSE). Defaults to TRUE.

1 (True - default)
0 (False)

selected: (integer) Category ID of the category to be 'selected' or presented in the display box. Defaults to no category selected.

hierarchical

(boolean) Display categories in hierarchical fashion (child categories show indented). Defaults to FALSE.

1 (True)
0 (False - Default)

name: (string) Name assigned to the dropdown form. Defaults to 'cat'.

class: (string) Class assinged to the dropdown form. Defaults to 'postform'.

depth

(integer) This parameter controls how many levels in the hierarchy of Categories are to be included in the list of Categories. The default value is 0 (display all Categories and their children). This parameter added at Version 2.5

0 - All Categories and child Categories (Default).
-1 - All Categories displayed in flat (no indent) form (overrides hierarchical).
1 - Show only top level Categories
n - Value of n (some number) specifies the depth (or level) to descend in displaying Categories

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">
   <?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 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">
<?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><input type="submit" value="View" /></noscript>
	</form>
</li>

Change Log

Since: 2.1.0

Source File

wp_dropdown_categories() is located in wp-includes/category-template.php.