get_categories( string|array $args = '' ): array

Retrieves a list of category objects.


Description

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

Top ↑

See also


Top ↑

Parameters

$args string|array Optional
Arguments to retrieve categories. See get_terms() for additional options.
  • taxonomy string
    Taxonomy to retrieve terms for. Default 'category'.
More Arguments from get_terms( ... $args ) Array or query string of term query parameters.
  • taxonomy string|string[]
    Taxonomy name, or array of taxonomy names, to which results should be limited.
  • object_ids int|int[]
    Object ID, or array of object IDs. Results will be limited to terms associated with these objects.
  • orderby string
    Field(s) to order terms by. Accepts:
    • Term fields ('name', 'slug', 'term_group', 'term_id', 'id', 'description', 'parent', 'term_order'). Unless $object_ids is not empty, 'term_order' is treated the same as 'term_id'.
    • 'count' to use the number of objects associated with the term.
    • 'include' to match the 'order' of the $include param.
    • 'slug__in' to match the 'order' of the $slug param.
    • 'meta_value'
    • 'meta_value_num'.
    • The value of $meta_key.
    • The array keys of $meta_query.
    • 'none' to omit the ORDER BY clause.
    Default 'name'.
  • order string
    Whether to order terms in ascending or descending order.
    Accepts 'ASC' (ascending) or 'DESC' (descending).
    Default 'ASC'.
  • hide_empty bool|int
    Whether to hide terms not assigned to any posts. Accepts 1|true or 0|false. Default 1|true.
  • include int[]|string
    Array or comma/space-separated string of term IDs to include.
    Default empty array.
  • exclude int[]|string
    Array or comma/space-separated string of term IDs to exclude.
    If $include is non-empty, $exclude is ignored.
    Default empty array.
  • exclude_tree int[]|string
    Array or comma/space-separated string of term IDs to exclude along with all of their descendant terms. If $include is non-empty, $exclude_tree is ignored. Default empty array.
  • number int|string
    Maximum number of terms to return. Accepts ''|0 (all) or any positive number. Default ''|0 (all). Note that $number may not return accurate results when coupled with $object_ids.
    See #41796 for details.
  • offset int
    The number by which to offset the terms query.
  • fields string
    Term fields to query for. Accepts:
    • 'all' Returns an array of complete term objects (WP_Term[]).
    • 'all_with_object_id' Returns an array of term objects with the 'object_id' param (WP_Term[]). Works only when the $object_ids parameter is populated.
    • 'ids' Returns an array of term IDs (int[]).
    • 'tt_ids' Returns an array of term taxonomy IDs (int[]).
    • 'names' Returns an array of term names (string[]).
    • 'slugs' Returns an array of term slugs (string[]).
    • 'count' Returns the number of matching terms (int).
    • 'id=>parent' Returns an associative array of parent term IDs, keyed by term ID (int[]).
    • 'id=>name' Returns an associative array of term names, keyed by term ID (string[]).
    • 'id=>slug' Returns an associative array of term slugs, keyed by term ID (string[]).
    Default 'all'.
  • count bool
    Whether to return a term count. If true, will take precedence over $fields. Default false.
  • name string|string[]
    Name or array of names to return term(s) for.
  • slug string|string[]
    Slug or array of slugs to return term(s) for.
  • term_taxonomy_id int|int[]
    Term taxonomy ID, or array of term taxonomy IDs, to match when querying terms.
  • hierarchical bool
    Whether to include terms that have non-empty descendants (even if $hide_empty is set to true). Default true.
  • search string
    Search criteria to match terms. Will be SQL-formatted with wildcards before and after.
  • name__like string
    Retrieve terms with criteria by which a term is LIKE $name__like.
  • description__like string
    Retrieve terms where the description is LIKE $description__like.
  • pad_counts bool
    Whether to pad the quantity of a term's children in the quantity of each term's "count" object variable. Default false.
  • get string
    Whether to return terms regardless of ancestry or whether the terms are empty. Accepts 'all' or '' (disabled). Default ''.
  • child_of int
    Term ID to retrieve child terms of. If multiple taxonomies are passed, $child_of is ignored. Default 0.
  • parent int
    Parent term ID to retrieve direct-child terms of.
  • childless bool
    True to limit results to terms that have no children.
    This parameter has no effect on non-hierarchical taxonomies.
    Default false.
  • cache_domain string
    Unique cache key to be produced when this query is stored in an object cache. Default 'core'.
  • cache_results bool
    Whether to cache term information. Default true.
  • update_term_meta_cache bool
    Whether to prime meta caches for matched terms. Default true.
  • meta_key string|string[]
    Meta key or keys to filter by.
  • meta_value string|string[]
    Meta value or values to filter by.
  • meta_compare string
    MySQL operator used for comparing the meta value.
    See WP_Meta_Query::__construct() for accepted values and default value.
  • meta_compare_key string
    MySQL operator used for comparing the meta key.
    See WP_Meta_Query::__construct() for accepted values and default value.
  • meta_type string
    MySQL data type that the meta_value column will be CAST to for comparisons.
    See WP_Meta_Query::__construct() for accepted values and default value.
  • meta_type_key string
    MySQL data type that the meta_key column will be CAST to for comparisons.
    See WP_Meta_Query::__construct() for accepted values and default value.
  • meta_query array
    An associative array of WP_Meta_Query arguments.
    See WP_Meta_Query::__construct() for accepted values.

Default: ''


Top ↑

Return

array List of category objects.


Top ↑

Source

File: wp-includes/category.php. View all references

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

Top ↑

Hooks



Top ↑

Changelog

Changelog
Version Description
2.1.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    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.

    <?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>';
    } 
  2. Skip to note 2 content
    Contributed by isMike()

    Function only returns categories in use by posts

    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.

    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.

    $args = array(
    			'hide_empty'      => false,
    		);
    		get_categories($args); //This returns both used and unused categories
  3. Skip to note 3 content
    Contributed by Codex

    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.

    $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 )
    	);
    }
  4. Skip to note 4 content
    Contributed by boundless_ink

    Specific category parent title with linked menu of subcategories

    – could be used in a sidebar application

    <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>
  5. Skip to note 6 content
    Contributed by Ahir Hemant

    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.

    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' );

    Output look like this:

    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 )

  6. Skip to note 7 content
    Contributed by Codex

    Drop-down box as used in Parent category at post category page
    This is the code used in the built-in category page.

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

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

    wp_dropdown_categories( array(
    	'hide_empty'   => 0,
    	'name'         => 'select_name',
    	'id'           => 'select_name',
    	'hierarchical' => true
    ) );
  7. Skip to note 8 content
    Contributed by Codex

    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() which shows how to create a drop-down 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"> 
    	<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>

You must log in before being able to contribute a note or feedback.