get_categories

Description

Returns an array of category objects matching the query parameters.

Arguments are pretty much the same as wp_list_categories and can be passed as either array or in query syntax.

Usage

<?php $categories = get_categories( $args ); ?>

Default Usage

<?php $args = array(
'type'                     => 'post',
'child_of'                 => 0,
'parent'                   => ,
'orderby'                  => 'name',
'order'                    => 'ASC',
'hide_empty'               => 1,
'hierarchical'             => 1,
'exclude'                  => ,
'include'                  => ,
'number'                   => ,
'taxonomy'                 => 'category',
'pad_counts'               => false );?>

Parameters

type

(string) Type of category to retrieve

• post – default
• link

Note: type=link has been deprecated from WordPress 3.0 onwards. Use taxonomy=link_category instead.

child_of

(integer) Display all categories that are descendants (i.e. children & grandchildren) of the category identified by its ID. There is no default for this parameter. If the parameter is used, the hide_empty parameter is set to false.

parent

(integer) Display only categories that are direct descendants (i.e. children only) of the category identified by its ID. This does NOT work like the ‘child_of’ parameter. There is no default for this parameter. [In 2.8.4]

orderby

(string) Sort categories alphabetically or by unique category ID. The default is sort by Category ID. Valid values:

• id
• name – default
• slug
• count
• term_group

order

(string) Sort order for categories (either ascending or descending). The default is ascending. Valid values:

• asc – default
• desc

hide_empty

(boolean) Toggles the display of categories with no posts. The default is 1 for true or you can add ‘0’ for false (show empty categories). Valid values:

• 1 – default
• 0

hierarchical

(boolean) When true, the results will include sub-categories that are empty, as long as those sub-categories have sub-categories that are not empty. The default is true. Valid values:

• 1 (true) – default
• 0 (false)

exclude

(string) Excludes one or more categories from the list generated by wp_list_categories. This parameter takes a comma-separated list of categories by unique ID, in ascending order. See the example.

include

(string) Only include certain categories in the list generated by wp_list_categories. This parameter takes a comma-separated list of categories by unique ID, in ascending order. See the example.

• list – default.
• none

number

(string) The number of categories to return

taxonomy

(string) Taxonomy to return. This parameter added at Version 3.0 Valid values:

• category – default
• taxonomy – or any registered taxonomy

pad_counts

(boolean) Calculates link or post counts by including items from child categories. Valid values:

• 1 (true)
• 0 (false) – default

Examples

Dropdown Box as used in Parent category at post category page

This is the code used in the build in category page. Code from 3.0.1

wp_dropdown_categories(array('hide_empty' => 0, 'name' => 'category_parent', 'orderby' => 'name', 'selected' => $category->parent, 'hierarchical' => true, 'show_option_none' => __('None')));

This slightly altered code will grab all categories and display them with indent for a new level (child category). The select box will have a name= and id= called ‘select_name’. This select will not display a default “none” as the original code was used to attach a category as a child to another category (or none).

wp_dropdown_categories(array('hide_empty' => 0, 'name' => 'select_name', 'hierarchical' => true));

Dropdown Box

Here’s how to create a dropdown box of the subcategories of, say, a category that archives information on past events. This mirrors the example of the dropdown example of wp_get_archives which shows how to create a dropdown box for monthly archives.

Suppose the category whose subcategories you want to show is category 10, and that its category “nicename” is “archives”.

<select name="event-dropdown" onchange='document.location.href=this.options[this.selectedIndex].value;'> 
 <option value=""><?php echo esc_attr(__('Select Event')); ?></option> 
 <?php 
  $categories=  get_categories('child_of=10'); 
  foreach ($categories as $category) {
  	$option = '<option value="/category/archives/'.$category->category_nicename.'">';
	$option .= $category->cat_name;
	$option .= ' ('.$category->category_count.')';
	$option .= '</option>';
	echo $option;
  }
 ?>
</select>

List Categories and Descriptions

This example will list in alphabetic order, all categories presented as links to the corresponding category archive. Each category descripition is listed after the category link.

<?php
$args=array(
  'orderby' => 'name',
  'order' => 'ASC'
  );
$categories=get_categories($args);
  foreach($categories as $category) { 
    echo '<p>Category: <a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . '>' . $category->name.'</a> </p> ';
    echo '<p> Description:'. $category->description . '</p>';
    echo '<p> Post Count: '. $category->count . '</p>';  } 
?>

The complete content of $category is:

$category->term_id
$category->name
$category->slug
$category->term_group
$category->term_taxonomy_id
$category->taxonomy
$category->description
$category->parent
$category->count
$category->cat_ID
$category->category_count
$category->category_description
$category->cat_name
$category->category_nicename
$category->category_parent

Source File

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