WordPress.org

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, 'orderby' => 'name', 'order' => 'ASC', 'hide_empty' => true, 'include_last_update_time' => false, 'hierarchical' => 1, 'exclude' => , 'include' => , 'number' => , 'pad_counts' => false );?>

Parameters

type

(string) Type of category to retreive

post - default
link

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
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 true (hide empty categories). Valid values:

1 (true) - default
0 (false)

include_last_update_time

(boolean) Uncertain what this doesies|the example]].

1 (true)
0 (false) -- default

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

pad_counts

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

1 (true)
0 (false) - default

Examples

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 attribute_escape(__('Select Event')); ?></option> 
 <?php 
  $categories=  get_categories('child_of=10'); 
  foreach ($categories as $cat) {
  	$option = '<option value="/category/archives/'.$cat->category_nicename.'">';
	$option .= $cat->cat_name;
	$option .= ' ('.$cat->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>'. $category->description . '</p>';
  } 
?>

WordPress.org

Codex