wp_list_categories

Display or retrieve the HTML list of categories.

Description

(false|string) wp_list_categories( (string) $args = '' ); 

Returns (false|string)

HTML content only if 'echo' argument is 0.

Parameters (1)

0. $args — Optional. (string) => ''
Array of optional arguments.

Options

  • child_of (int) => 0

    Term ID to retrieve child terms of. See get_terms().

  • current_category (int|array) => 0

    ID of category, or array of IDs of categories, that should get the current-cat class.

  • depth (int) => 0

    Category depth. Used for tab indentation.

  • echo (bool|int) => 1

    True to echo markup, false to return it.

  • exclude (array|string) => string

    Array or comma/space-separated string of term IDs to exclude. If $hierarchical is true, descendants of $exclude. terms will also be excluded; see $exclude_tree. See get_terms().

  • exclude_tree (array|string) => string

    Array or comma/space-separated string of term IDs to exclude, along with their descendants. See get_terms().

  • feed (string) => 'Feed for all posts filed under [cat name]'

    Text to use for the feed link.

  • feed_image (string) => string

    URL of an image to use for the feed link.

  • feed_type (string) => string (default feed)

    Feed type. Used to build feed link. See get_term_feed_link().

  • hide_empty (bool|int) => 1

    Whether to hide categories that don't have any posts attached to them.

  • hide_title_if_empty (bool) => false (title will always be shown)

    Whether to hide the $title_li element if there are no terms in the list.

  • hierarchical (bool) => true

    Whether to include terms that have non-empty descendants. See get_terms().

  • order (string) => 'ASC'

    Which direction to order categories. Accepts ASC or DESC..

  • orderby (string) => 'ID'

    The column to use for ordering categories.

  • separator (string) => '
    '

    Separator between links.

  • show_count (bool|int) => 0

    Whether to show how many posts are in the category.

  • show_option_all (string) => string

    Text to display for showing all categories.

  • show_option_none (string) => 'No categories'

    Text to display for the no categories option.

  • style (string) => 'list'

    The style used to display the categories list. If list,, categories will be output as an unordered list. If left empty or another value, categories will be output separated by
    tags.

  • taxonomy (string) => 'category'

    Taxonomy name.

  • title_li (string) => 'Categories'

    Text to use for the list title

  • element. Pass an empty string to disable.

array(

    /**
     * Term ID to retrieve child terms of. See get_terms().
     *
     * @type int
     */
    'child_of' => 0,

    /**
     * ID of category, or array of IDs of categories, that should get the 'current-cat' class.
     *
     * @type int|array
     */
    'current_category' => 0,

    /**
     * Category depth. Used for tab indentation.
     *
     * @type int
     */
    'depth' => 0,

    /**
     * True to echo markup, false to return it.
     *
     * @type bool|int
     * @default 1
     */
    'echo' => 1,

    /**
     * Array or comma/space-separated string of term IDs to exclude. If `$hierarchical` is true,
     * descendants of `$exclude` terms will also be excluded; see `$exclude_tree`. See
     * get_terms().
     *
     * @type array|string
     * @default string
     */
    'exclude' => string,

    /**
     * Array or comma/space-separated string of term IDs to exclude, along with their descendants.
     * See get_terms().
     *
     * @type array|string
     * @default string
     */
    'exclude_tree' => string,

    /**
     * Text to use for the feed link.
     *
     * @type string
     * @default 'Feed for all posts filed under [cat name]'
     */
    'feed' => 'Feed for all posts filed under [cat name]',

    /**
     * URL of an image to use for the feed link.
     *
     * @type string
     * @default string
     */
    'feed_image' => string,

    /**
     * Feed type. Used to build feed link. See get_term_feed_link().
     *
     * @type string
     * @default string (default feed)
     */
    'feed_type' => string (default feed),

    /**
     * Whether to hide categories that don't have any posts attached to them.
     *
     * @type bool|int
     * @default 1
     */
    'hide_empty' => 1,

    /**
     * Whether to hide the `$title_li` element if there are no terms in the list.
     *
     * @type bool
     * @default false (title will always be shown)
     */
    'hide_title_if_empty' => false (title will always be shown),

    /**
     * Whether to include terms that have non-empty descendants. See get_terms().
     *
     * @type bool
     * @default true
     */
    'hierarchical' => true,

    /**
     * Which direction to order categories. Accepts 'ASC' or 'DESC'.
     *
     * @type string
     * @default 'ASC'
     */
    'order' => 'ASC',

    /**
     * The column to use for ordering categories.
     *
     * @type string
     * @default 'ID'
     */
    'orderby' => 'ID',

    /**
     * Separator between links.
     *
     * @type string
     * @default '
' */
'separator' => '
'
, /** * Whether to show how many posts are in the category. * * @type bool|int */ 'show_count' => 0, /** * Text to display for showing all categories. * * @type string * @default string */ 'show_option_all' => string, /** * Text to display for the 'no categories' option. * * @type string * @default 'No categories' */ 'show_option_none' => 'No categories', /** * The style used to display the categories list. If 'list', categories will be output as an * unordered list. If left empty or another value, categories will be output separated by `` * tags. * * @type string * @default 'list' */ 'style' => 'list', /** * Taxonomy name. * * @type string * @default 'category' */ 'taxonomy' => 'category', /** * Text to use for the list title `` element. Pass an empty string to disable. * * @type string * @default 'Categories' */ 'title_li' => 'Categories' );


Usage

  1. if ( !function_exists( 'wp_list_categories' ) ) { 
  2. require_once ABSPATH . WPINC . '/category-template.php'; 
  3.  
  4. // Array of optional arguments. 
  5. $args = array( 
  6. 'child_of' => 0, 
  7. 'current_category' => 0, 
  8. 'depth' => 0, 
  9. 'echo' => 1, 
  10. 'exclude' => string, 
  11. 'exclude_tree' => string, 
  12. 'feed' => 'Feed for all posts filed under [cat name]', 
  13. 'feed_image' => string, 
  14. 'feed_type' => string (default feed), 
  15. 'hide_empty' => 1, 
  16. 'hide_title_if_empty' => false (title will always be shown), 
  17. 'hierarchical' => true, 
  18. 'order' => 'ASC', 
  19. 'orderby' => 'ID', 
  20. 'separator' => '', 
  21. 'show_count' => 0, 
  22. 'show_option_all' => string, 
  23. 'show_option_none' => 'No categories', 
  24. 'style' => 'list', 
  25. 'taxonomy' => 'category', 
  26. 'title_li' => 'Categories' 
  27. ); 
  28.  
  29. // NOTICE! Understand what this does before running. 
  30. $result = wp_list_categories($args); 
  31.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/category-template.php  
  1. function wp_list_categories( $args = '' ) { 
  2. $defaults = array( 
  3. 'child_of' => 0,  
  4. 'current_category' => 0,  
  5. 'depth' => 0,  
  6. 'echo' => 1,  
  7. 'exclude' => '',  
  8. 'exclude_tree' => '',  
  9. 'feed' => '',  
  10. 'feed_image' => '',  
  11. 'feed_type' => '',  
  12. 'hide_empty' => 1,  
  13. 'hide_title_if_empty' => false,  
  14. 'hierarchical' => true,  
  15. 'order' => 'ASC',  
  16. 'orderby' => 'name',  
  17. 'separator' => '<br />',  
  18. 'show_count' => 0,  
  19. 'show_option_all' => '',  
  20. 'show_option_none' => __( 'No categories' ),  
  21. 'style' => 'list',  
  22. 'taxonomy' => 'category',  
  23. 'title_li' => __( 'Categories' ),  
  24. 'use_desc_for_title' => 1,  
  25. ); 
  26.  
  27. $r = wp_parse_args( $args, $defaults ); 
  28.  
  29. if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) 
  30. $r['pad_counts'] = true; 
  31.  
  32. // Descendants of exclusions should be excluded too. 
  33. if ( true == $r['hierarchical'] ) { 
  34. $exclude_tree = array(); 
  35.  
  36. if ( $r['exclude_tree'] ) { 
  37. $exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $r['exclude_tree'] ) ); 
  38.  
  39. if ( $r['exclude'] ) { 
  40. $exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $r['exclude'] ) ); 
  41.  
  42. $r['exclude_tree'] = $exclude_tree; 
  43. $r['exclude'] = ''; 
  44.  
  45. if ( ! isset( $r['class'] ) ) 
  46. $r['class'] = ( 'category' == $r['taxonomy'] ) ? 'categories' : $r['taxonomy']; 
  47.  
  48. if ( ! taxonomy_exists( $r['taxonomy'] ) ) { 
  49. return false; 
  50.  
  51. $show_option_all = $r['show_option_all']; 
  52. $show_option_none = $r['show_option_none']; 
  53.  
  54. $categories = get_categories( $r ); 
  55.  
  56. $output = ''; 
  57. if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $categories ) || ! $r['hide_title_if_empty'] ) ) { 
  58. $output = '<li class="' . esc_attr( $r['class'] ) . '">' . $r['title_li'] . '<ul>'; 
  59. if ( empty( $categories ) ) { 
  60. if ( ! empty( $show_option_none ) ) { 
  61. if ( 'list' == $r['style'] ) { 
  62. $output .= '<li class="cat-item-none">' . $show_option_none . '</li>'; 
  63. } else { 
  64. $output .= $show_option_none; 
  65. } else { 
  66. if ( ! empty( $show_option_all ) ) { 
  67.  
  68. $posts_page = ''; 
  69.  
  70. // For taxonomies that belong only to custom post types, point to a valid archive. 
  71. $taxonomy_object = get_taxonomy( $r['taxonomy'] ); 
  72. if ( ! in_array( 'post', $taxonomy_object->object_type ) && ! in_array( 'page', $taxonomy_object->object_type ) ) { 
  73. foreach ( $taxonomy_object->object_type as $object_type ) { 
  74. $_object_type = get_post_type_object( $object_type ); 
  75.  
  76. // Grab the first one. 
  77. if ( ! empty( $_object_type->has_archive ) ) { 
  78. $posts_page = get_post_type_archive_link( $object_type ); 
  79. break; 
  80.  
  81. // Fallback for the 'All' link is the posts page. 
  82. if ( ! $posts_page ) { 
  83. if ( 'page' == get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) ) { 
  84. $posts_page = get_permalink( get_option( 'page_for_posts' ) ); 
  85. } else { 
  86. $posts_page = home_url( '/' ); 
  87.  
  88. $posts_page = esc_url( $posts_page ); 
  89. if ( 'list' == $r['style'] ) { 
  90. $output .= "<li class='cat-item-all'><a href='$posts_page'>$show_option_all</a></li>"; 
  91. } else { 
  92. $output .= "<a href='$posts_page'>$show_option_all</a>"; 
  93.  
  94. if ( empty( $r['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) { 
  95. $current_term_object = get_queried_object(); 
  96. if ( $current_term_object && $r['taxonomy'] === $current_term_object->taxonomy ) { 
  97. $r['current_category'] = get_queried_object_id(); 
  98.  
  99. if ( $r['hierarchical'] ) { 
  100. $depth = $r['depth']; 
  101. } else { 
  102. $depth = -1; // Flat. 
  103. $output .= walk_category_tree( $categories, $depth, $r ); 
  104.  
  105. if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $categories ) || ! $r['hide_title_if_empty'] ) ) { 
  106. $output .= '</ul></li>'; 
  107.  
  108. /** 
  109. * Filters the HTML output of a taxonomy list. 
  110. * @since 2.1.0 
  111. * @param string $output HTML output. 
  112. * @param array $args An array of taxonomy-listing arguments. 
  113. */ 
  114. $html = apply_filters( 'wp_list_categories', $output, $args ); 
  115.  
  116. if ( $r['echo'] ) { 
  117. echo $html; 
  118. } else { 
  119. return $html;