wp_list_categories( array|string $args = ” )

You are here:
  • KB Home
  • wp_list_categories( array|string $args = ” )

Parameters Parameters

$args

(array|string) (Optional) Array of optional arguments. See get_categories()get_terms(), and WP_Term_Query::__construct() for information on additional accepted arguments.

  • ‘current_category’
    (int|array) ID of category, or array of IDs of categories, that should get the ‘current-cat’ class. Default 0.
  • ‘depth’
    (int) Category depth. Used for tab indentation. Default 0.
  • ‘echo’
    (bool|int) Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents. Default 1.
  • ‘exclude’
    (array|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) Array or comma/space-separated string of term IDs to exclude, along with their descendants. See get_terms().
  • ‘feed’
    (string) Text to use for the feed link. Default ‘Feed for all posts filed under [cat name]’.
  • ‘feed_image’
    (string) URL of an image to use for the feed link.
  • ‘feed_type’
    (string) Feed type. Used to build feed link. See get_term_feed_link(). Default empty string (default feed).
  • ‘hide_title_if_empty’
    (bool) Whether to hide the $title_li element if there are no terms in the list. Default false (title will always be shown).
  • ‘separator’
    (string) Separator between links. Default <br />.
  • ‘show_count’
    (bool|int) Whether to include post counts. Accepts 0, 1, or their bool equivalents. Default 0.
  • ‘show_option_all’
    (string) Text to display for showing all categories.
  • ‘show_option_none’
    (string) Text to display for the ‘no categories’ option. Default ‘No categories’.
  • ‘style’
    (string) 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 <br> tags. Default ‘list’.
  • ‘title_li’
    (string) Text to use for the list title <li> element. Pass an empty string to disable. Default ‘Categories’.
  • ‘use_desc_for_title’
    (bool|int) Whether to use the category description as the title attribute. Accepts 0, 1, or their bool equivalents. Default 1.

 

Default value: ”


Top ↑

Return Return

(void|string|false) Void if ‘echo’ argument is true, HTML list of categories if ‘echo’ is false. False if the taxonomy does not exist.


Top ↑

More Information More Information

If you need a function that does not format the results, try get_categories().

Usage Usage

By default, wp_list_categories() displays:

  • No link to all categories
  • Sorts the list of Categories by the Category name in ascending order
  • Displayed in an unordered list style
  • Does not show the post count
  • Displays only Categories with posts
  • Sets the title attribute to the Category Description
  • Is not restricted to the child_of any Category
  • No feed or feed image used
  • Does not exclude any Category and includes all Categories
  • Displays the active Category with the CSS Class-Suffix ‘ current-cat’
  • Shows the Categories in hierarchical indented fashion
  • Display Category as the heading over the list
  • No SQL LIMIT is imposed (‘number’ => 0 is not shown above)
  • Displays (echos) the categories
  • No limit to depth
  • All categories.
  • The list is rendered using a new walker object of the the Walker_Category class

Top ↑

Source Source

File: wp-includes/category-template.php

523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
function wp_list_categories( $args = '' ) {
    $defaults = array(
        'child_of'            => 0,
        'current_category'    => 0,
        'depth'               => 0,
        'echo'                => 1,
        'exclude'             => '',
        'exclude_tree'        => '',
        'feed'                => '',
        'feed_image'          => '',
        'feed_type'           => '',
        'hide_empty'          => 1,
        'hide_title_if_empty' => false,
        'hierarchical'        => true,
        'order'               => 'ASC',
        'orderby'             => 'name',
        'separator'           => '<br />',
        'show_count'          => 0,
        'show_option_all'     => '',
        'show_option_none'    => __( 'No categories' ),
        'style'               => 'list',
        'taxonomy'            => 'category',
        'title_li'            => __( 'Categories' ),
        'use_desc_for_title'  => 1,
    );
 
    $parsed_args = wp_parse_args( $args, $defaults );
 
    if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) {
        $parsed_args['pad_counts'] = true;
    }
 
    // Descendants of exclusions should be excluded too.
    if ( true == $parsed_args['hierarchical'] ) {
        $exclude_tree = array();
 
        if ( $parsed_args['exclude_tree'] ) {
            $exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $parsed_args['exclude_tree'] ) );
        }
 
        if ( $parsed_args['exclude'] ) {
            $exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $parsed_args['exclude'] ) );
        }
 
        $parsed_args['exclude_tree'] = $exclude_tree;
        $parsed_args['exclude']      = '';
    }
 
    if ( ! isset( $parsed_args['class'] ) ) {
        $parsed_args['class'] = ( 'category' === $parsed_args['taxonomy'] ) ? 'categories' : $parsed_args['taxonomy'];
    }
 
    if ( ! taxonomy_exists( $parsed_args['taxonomy'] ) ) {
        return false;
    }
 
    $show_option_all  = $parsed_args['show_option_all'];
    $show_option_none = $parsed_args['show_option_none'];
 
    $categories = get_categories( $parsed_args );
 
    $output = '';
 
    if ( $parsed_args['title_li'] && 'list' === $parsed_args['style']
        && ( ! empty( $categories ) || ! $parsed_args['hide_title_if_empty'] )
    ) {
        $output = '<li class="' . esc_attr( $parsed_args['class'] ) . '">' . $parsed_args['title_li'] . '<ul>';
    }
 
    if ( empty( $categories ) ) {
        if ( ! empty( $show_option_none ) ) {
            if ( 'list' === $parsed_args['style'] ) {
                $output .= '<li class="cat-item-none">' . $show_option_none . '</li>';
            } else {
                $output .= $show_option_none;
            }
        }
    } else {
        if ( ! empty( $show_option_all ) ) {
 
            $posts_page = '';
 
            // For taxonomies that belong only to custom post types, point to a valid archive.
            $taxonomy_object = get_taxonomy( $parsed_args['taxonomy'] );
            if ( ! in_array( 'post', $taxonomy_object->object_type, true ) && ! in_array( 'page', $taxonomy_object->object_type, true ) ) {
                foreach ( $taxonomy_object->object_type as $object_type ) {
                    $_object_type = get_post_type_object( $object_type );
 
                    // Grab the first one.
                    if ( ! empty( $_object_type->has_archive ) ) {
                        $posts_page = get_post_type_archive_link( $object_type );
                        break;
                    }
                }
            }
 
            // Fallback for the 'All' link is the posts page.
            if ( ! $posts_page ) {
                if ( 'page' === get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) ) {
                    $posts_page = get_permalink( get_option( 'page_for_posts' ) );
                } else {
                    $posts_page = home_url( '/' );
                }
            }
 
            $posts_page = esc_url( $posts_page );
            if ( 'list' === $parsed_args['style'] ) {
                $output .= "<li class='cat-item-all'><a href='$posts_page'>$show_option_all</a></li>";
            } else {
                $output .= "<a href='$posts_page'>$show_option_all</a>";
            }
        }
 
        if ( empty( $parsed_args['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) {
            $current_term_object = get_queried_object();
            if ( $current_term_object && $parsed_args['taxonomy'] === $current_term_object->taxonomy ) {
                $parsed_args['current_category'] = get_queried_object_id();
            }
        }
 
        if ( $parsed_args['hierarchical'] ) {
            $depth = $parsed_args['depth'];
        } else {
            $depth = -1; // Flat.
        }
        $output .= walk_category_tree( $categories, $depth, $parsed_args );
    }
 
    if ( $parsed_args['title_li'] && 'list' === $parsed_args['style']
        && ( ! empty( $categories ) || ! $parsed_args['hide_title_if_empty'] )
    ) {
        $output .= '</ul></li>';
    }
 
    /**
     * Filters the HTML output of a taxonomy list.
     *
     * @since 2.1.0
     *
     * @param string $output HTML output.
     * @param array  $args   An array of taxonomy-listing arguments.
     */
    $html = apply_filters( 'wp_list_categories', $output, $args );
 
    if ( $parsed_args['echo'] ) {
        echo $html;
    } else {
        return $html;
    }
}


Top ↑

Changelog Changelog

Changelog
VersionDescription
4.4.0The current_category argument was modified to optionally accept an array of values.
2.1.0Introduced.
Was this article helpful?
Dislike 0
Views: 1

Cart

Log in

Create an Account
Back to Top