Title: get_categories
Published: April 25, 2014
Last modified: February 24, 2026

---

# get_categories( string|array $args ): array

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#description)
    - [See also](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#see-also)
 * [Parameters](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#changelog)
 * [User Contributed Notes](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#user-contributed-notes)

[ Back to top](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#wp--skip-link--target)

Retrieves a list of category objects.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#description)󠁿

If you set the ‘taxonomy’ argument to ‘link_category’, the link categories will 
be returned instead.

### 󠀁[See also](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#see-also)󠁿

 * [get_terms()](https://developer.wordpress.org/reference/functions/get_terms/):
   Type of arguments that can be changed.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#parameters)󠁿

 `$args`string|arrayoptional

Arguments to retrieve categories. See [get_terms()](https://developer.wordpress.org/reference/functions/get_terms/)
for additional options.

 * `taxonomy` string
 * Taxonomy to retrieve terms for. Default `'category'`.

More Arguments from get_terms( … $args )

Array or string of arguments. See [WP_Term_Query::__construct()](https://developer.wordpress.org/reference/classes/wp_term_query/__construct/)
for information on accepted arguments.

## 󠀁[Return](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#return)󠁿

 array List of category objects.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#source)󠁿

    ```php
    function get_categories( $args = '' ) {
    	$defaults = array( 'taxonomy' => 'category' );
    	$args     = wp_parse_args( $args, $defaults );

    	/**
    	 * Filters the taxonomy used to retrieve terms when calling get_categories().
    	 *
    	 * @since 2.7.0
    	 *
    	 * @param string $taxonomy Taxonomy to retrieve terms from.
    	 * @param array  $args     An array of arguments. See get_terms().
    	 */
    	$args['taxonomy'] = apply_filters( 'get_categories_taxonomy', $args['taxonomy'], $args );

    	// Back compat.
    	if ( isset( $args['type'] ) && 'link' === $args['type'] ) {
    		_deprecated_argument(
    			__FUNCTION__,
    			'3.0.0',
    			sprintf(
    				/* translators: 1: "type => link", 2: "taxonomy => link_category" */
    				__( '%1$s is deprecated. Use %2$s instead.' ),
    				'<code>type => link</code>',
    				'<code>taxonomy => link_category</code>'
    			)
    		);
    		$args['taxonomy'] = 'link_category';
    	}

    	$categories = get_terms( $args );

    	if ( is_wp_error( $categories ) ) {
    		$categories = array();
    	} else {
    		$categories = (array) $categories;
    		foreach ( array_keys( $categories ) as $k ) {
    			_make_cat_compat( $categories[ $k ] );
    		}
    	}

    	return $categories;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/category.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/category.php#L26)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/category.php#L26-L67)

## 󠀁[Hooks](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#hooks)󠁿

 [apply_filters( ‘get_categories_taxonomy’, string $taxonomy, array $args )](https://developer.wordpress.org/reference/hooks/get_categories_taxonomy/)

Filters the taxonomy used to retrieve terms when calling [get_categories()](https://developer.wordpress.org/reference/functions/get_categories/).

## 󠀁[Related](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#related)󠁿

| Uses | Description | 
| [_make_cat_compat()](https://developer.wordpress.org/reference/functions/_make_cat_compat/)`wp-includes/category.php` |

Updates category structure to old pre-2.3 from new taxonomy structure.

  | 
| [get_terms()](https://developer.wordpress.org/reference/functions/get_terms/)`wp-includes/taxonomy.php` |

Retrieves the terms in a given taxonomy or list of taxonomies.

  | 
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |

Retrieves the translation of $text.

  | 
| [_deprecated_argument()](https://developer.wordpress.org/reference/functions/_deprecated_argument/)`wp-includes/functions.php` |

Marks a function argument as deprecated and inform when it has been used.

  | 
| [wp_parse_args()](https://developer.wordpress.org/reference/functions/wp_parse_args/)`wp-includes/functions.php` |

Merges user defined arguments into defaults array.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  | 
| [is_wp_error()](https://developer.wordpress.org/reference/functions/is_wp_error/)`wp-includes/load.php` |

Checks whether the given variable is a WordPress Error.

  |

[Show 5 more](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#)

| Used by | Description | 
| [export_wp()](https://developer.wordpress.org/reference/functions/export_wp/)`wp-admin/includes/export.php` |

Generates the WXR export file for download.

  | 
| [wp_dropdown_cats()](https://developer.wordpress.org/reference/functions/wp_dropdown_cats/)`wp-admin/includes/deprecated.php` |

Legacy function used for generating a categories drop-down control.

  | 
| [wp_list_categories()](https://developer.wordpress.org/reference/functions/wp_list_categories/)`wp-includes/category-template.php` |

Displays or retrieves the HTML list of categories.

  | 
| [get_links_list()](https://developer.wordpress.org/reference/functions/get_links_list/)`wp-includes/deprecated.php` |

Output entire list of links by category.

  | 
| [wp_xmlrpc_server::mw_getCategories()](https://developer.wordpress.org/reference/classes/wp_xmlrpc_server/mw_getcategories/)`wp-includes/class-wp-xmlrpc-server.php` |

Retrieves the list of categories on a given blog.

  | 
| [wp_xmlrpc_server::mt_getCategoryList()](https://developer.wordpress.org/reference/classes/wp_xmlrpc_server/mt_getcategorylist/)`wp-includes/class-wp-xmlrpc-server.php` |

Retrieves the list of all categories on a blog.

  | 
| [wp_xmlrpc_server::wp_suggestCategories()](https://developer.wordpress.org/reference/classes/wp_xmlrpc_server/wp_suggestcategories/)`wp-includes/class-wp-xmlrpc-server.php` |

Retrieves category list.

  |

[Show 2 more](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#)

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#changelog)󠁿

| Version | Description | 
| [2.1.0](https://developer.wordpress.org/reference/since/2.1.0/) | Introduced. |

## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#user-contributed-notes)󠁿

 1.   [Skip to note 9 content](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#comment-content-333)
 2.    [Codex](https://profiles.wordpress.org/codex/)  [  11 years ago  ](https://developer.wordpress.org/reference/functions/get_categories/#comment-333)
 3.  [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-333)
     Vote results for this note: 16[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-333)
 4.  **List Categories and Descriptions**
      This example will list, in alphabetic order,
     all categories presented as links to the corresponding category archive. Each 
     category description is listed after the category link.
 5.      ```php
         <?php
         $categories = get_categories( array(
         	'orderby' => 'name',
         	'order'   => 'ASC'
         ) );
     
         foreach( $categories as $category ) {
         	$category_link = sprintf( 
         		'<a href="%1$s" alt="%2$s">%3$s</a>',
         		esc_url( get_category_link( $category->term_id ) ),
         		esc_attr( sprintf( __( 'View all posts in %s', 'textdomain' ), $category->name ) ),
         		esc_html( $category->name )
         	);
     
         	echo '<p>' . sprintf( esc_html__( 'Category: %s', 'textdomain' ), $category_link ) . '</p> ';
         	echo '<p>' . sprintf( esc_html__( 'Description: %s', 'textdomain' ), $category->description ) . '</p>';
         	echo '<p>' . sprintf( esc_html__( 'Post Count: %s', 'textdomain' ), $category->count ) . '</p>';
         } 
         ```
     
 6.   [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%3Freplytocom%3D333%23feedback-editor-333)
 7.   [Skip to note 10 content](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#comment-content-3081)
 8.    [isMike()](https://profiles.wordpress.org/sleekdevigner/)  [  7 years ago  ](https://developer.wordpress.org/reference/functions/get_categories/#comment-3081)
 9.  [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-3081)
     Vote results for this note: 12[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-3081)
 10. **Function only returns categories in use by posts**
 11. It is very important to note that by default, the `get_category()` will ONLY return
     categories that ARE IN USE. This means if no post is assigned to the category,
     then the category object for that category is not returned.
 12. This means if you are developer, and you created a category (maybe during testing),
     you should supply an argument array having the `'hide_empty' => false` in it. 
     Check the example usage below.
 13.     ```php
         $args = array(
         			'hide_empty'      => false,
         		);
         		get_categories($args); //This returns both used and unused categories
         ```
     
 14.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%3Freplytocom%3D3081%23feedback-editor-3081)
 15.  [Skip to note 11 content](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#comment-content-334)
 16.   [Codex](https://profiles.wordpress.org/codex/)  [  11 years ago  ](https://developer.wordpress.org/reference/functions/get_categories/#comment-334)
 17. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-334)
     Vote results for this note: 8[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-334)
 18. **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.
 19.     ```php
         $categories = get_categories( array(
         	'orderby' => 'name',
         	'parent'  => 0
         ) );
     
         foreach ( $categories as $category ) {
         	printf( '<a href="%1$s">%2$s</a><br />',
         		esc_url( get_category_link( $category->term_id ) ),
         		esc_html( $category->name )
         	);
         }
         ```
     
 20.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%3Freplytocom%3D334%23feedback-editor-334)
 21.  [Skip to note 12 content](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#comment-content-4977)
 22.   [boundless_ink](https://profiles.wordpress.org/boundlessink/)  [  5 years ago  ](https://developer.wordpress.org/reference/functions/get_categories/#comment-4977)
 23. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-4977)
     Vote results for this note: 1[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-4977)
 24. **Specific category parent title with linked menu of subcategories**
 25. – could be used in a sidebar application
 26.     ```php
         <div class="category-menu-container">
     
         			<ul class="category-menu">
         				<li class="unstyled">
         					<h4 class="category-menu-heading">
         						<?php echo get_cat_name( $category_id = 130 );?>
         					</h4>
         				</li>
         				<?php 
         				$categories = get_categories( array(
         					'orderby' => 'name',
         					'order'   => 'ASC',
         					'parent'  => 130,
         				) );
     
         				foreach( $categories as $category ) {
         					$category_link = sprintf( 
         						'<a href="%1$s" alt="%2$s">%3$s</a>',
         						esc_url( get_category_link( $category->term_id ) ),
         						esc_attr( sprintf( __( 'View all posts in %s', 'textdomain' ), $category->name ) ),
         						esc_html( $category->name )
         					);
     
         					echo '<p>' . sprintf( esc_html__( '%s', 'textdomain' ), $category_link ) . '</p> ';
         				}
         				?>
         			</ul>
     
         		</div>
         ```
     
 27.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%3Freplytocom%3D4977%23feedback-editor-4977)
 28.  [Skip to note 13 content](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#comment-content-2711)
 29.   [cameronamcintyre](https://profiles.wordpress.org/cameronamcintyre/)  [  8 years ago  ](https://developer.wordpress.org/reference/functions/get_categories/#comment-2711)
 30. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-2711)
     Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-2711)
 31. If there are no categories to display, `get_categories()` will return an empty
     array.
 32.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%3Freplytocom%3D2711%23feedback-editor-2711)
 33.  [Skip to note 14 content](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#comment-content-6398)
 34.   [Ahir Hemant](https://profiles.wordpress.org/hemant-ahir/)  [  3 years ago  ](https://developer.wordpress.org/reference/functions/get_categories/#comment-6398)
 35. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-6398)
     Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-6398)
 36. get all parent categories, and then based on parent id you can write a recurring
     function that gives you the child category of given id.
 37.     ```php
         function wpdocs_get_child_categories( $parent_category_id ) {
             $html = '';
             $child_categories = get_categories( array( 'parent' => $parent_category_id, 'hide_empty' => false, 'taxonomy' => $taxonomy ) );
             if ( ! empty( $child_categories ) ) {
                 $html .= '<ul>';
                 foreach ( $child_categories as $child_category ) {
                     $html .= '<li>'.$child_category->name;
                     $html .= get_child_categories( $child_category->term_id );
                     $html .= '</li>';
                 }
                 $html .= '</ul>';
             }
             return $html;
         }
     
         function wpdocs_list_categories() {
             $html = '';
             $parent_categories = get_categories( array( 'parent' => 0, 'hide_empty' => false, 'taxonomy' => $taxonomy ) );
             $html .= '<ul>';
             foreach ( $parent_categories as $parent_category ) {
                 $html .= '<li>';
                 $html .= $parent_category->name;
                 $html .= wpdocs_get_child_categories( $parent_category->term_id  );
                 $html .= '</li>';
             }
             $html.= '</ul>';
             return $html;
         }
         add_shortcode( 'wpdocs_list_categories', 'wpdocs_list_categories' );
         ```
     
 38. Output look like this:
 39. A – Main category
      B    – Child Category C    – Child Category D      – Nested
     Child Category( if available ) E – Main category F    – Child Category G    – 
     Child Category H     – Nested Child Category( if available )
 40.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%3Freplytocom%3D6398%23feedback-editor-6398)
 41.  [Skip to note 15 content](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#comment-content-331)
 42.   [Codex](https://profiles.wordpress.org/codex/)  [  11 years ago  ](https://developer.wordpress.org/reference/functions/get_categories/#comment-331)
 43. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-331)
     Vote results for this note: -2[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-331)
 44. **Drop-down box as used in Parent category at post category page**
      This is the
     code used in the built-in category page.
 45.     ```php
         wp_dropdown_categories( array(
         	'hide_empty'       => 0,
         	'name'             => 'category_parent',
         	'orderby'          => 'name',
         	'selected'         => $category->parent,
         	'hierarchical'     => true,
         	'show_option_none' => __('None')
         ) );
         ```
     
 46. The slightly altered code below will grab all categories and display them with
     indent for a new level (child category). The select box will have name and id 
     attribute values of ‘select_name’. This select element will not display a default“
     none” as the original code was used to attach a category as a child to another
     category (or none).
 47.     ```php
         wp_dropdown_categories( array(
         	'hide_empty'   => 0,
         	'name'         => 'select_name',
         	'id'           => 'select_name',
         	'hierarchical' => true
         ) );
         ```
     
 48.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%3Freplytocom%3D331%23feedback-editor-331)
 49.  [Skip to note 16 content](https://developer.wordpress.org/reference/functions/get_categories/?output_format=md#comment-content-332)
 50.   [Codex](https://profiles.wordpress.org/codex/)  [  11 years ago  ](https://developer.wordpress.org/reference/functions/get_categories/#comment-332)
 51. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-332)
     Vote results for this note: -2[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%23comment-332)
 52. **Drop-down Box**
      Here’s how to create a drop-down box of the subcategories of,
     say, a category that archives information on past events. This mirrors the example
     of the drop-down example of `[wp_get_archives()](https://developer.wordpress.org/reference/functions/wp_get_archives/)`
     which shows how to create a drop-down box for monthly archives.
 53. Suppose the category whose subcategories you want to show is category 10, and 
     that its category “nicename” is “archives”.
 54.     ```php
         <select name="event-dropdown"> 
         	<option value=""><?php echo esc_attr_e( 'Select Event', 'textdomain' ); ?></option> 
         	<?php 
         	$categories = get_categories( array( 'child_of' => 10 ) ); 
         	foreach ( $categories as $category ) {
         		printf( '<option value="%1$s">%2$s (%3$s)</option>',
         			esc_attr( '/category/archives/' . $category->category_nicename ),
         			esc_html( $category->cat_name ),
         			esc_html( $category->category_count )
         		);
           	}
          	?>
         </select>
         ```
     
 55.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F%3Freplytocom%3D332%23feedback-editor-332)

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_categories%2F)
before being able to contribute a note or feedback.