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
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:
- 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:
- 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.
- 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
