WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/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 name. 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 or array) 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

Return values

(array) 
Returns an array of category objects matching the query parameters.

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

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>';  } 
?>

Get only top level categories

To get the top level categories only, set parent value to zero. This example gets link and name of top level categories.

<?php
$args = array(
  'orderby' => 'name',
  'parent' => 0
  );
$categories = get_categories( $args );
foreach ( $categories as $category ) {
	echo '<a href="' . get_category_link( $category->term_id ) . '">' . $category->name . '</a><br/>';
}
?>

Source File

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

See also index of Function Reference and index of Template Tags.