Creates an HTML list of categories.

Since: 2.1.0
Source: wp-includes/class-walker-category.php
Used by: wp_list_categories()

Class Synopsis

class Walker_Category extends Walker {
    public $tree_type = 'category';
    public $db_fields = [
        'parent' => 'parent',
        'id'     => 'term_id',
    ];
    
    public function start_lvl( &$output, $depth = 0, $args = [] );
    public function end_lvl( &$output, $depth = 0, $args = [] );
    public function start_el( &$output, $data_object, $depth = 0, $args = [], $current_object_id = 0 );
    public function end_el( &$output, $data_object, $depth = 0, $args = [] );
}

Configuration

$db_fields

public $db_fields = [
    'parent' => 'parent',    // WP_Term->parent
    'id'     => 'term_id',   // WP_Term->term_id
];

Methods

start_lvl()

Opens a child category list. Only outputs if $args['style'] === 'list'.

public function start_lvl( &$output, $depth = 0, $args = [] )

Output:

<ul class='children'>

end_lvl()

Closes the child category list.

public function end_lvl( &$output, $depth = 0, $args = [] )

Output:

</ul>

start_el()

Outputs a category list item with link.

public function start_el( &$output, $data_object, $depth = 0, $args = [], $current_object_id = 0 )

Args used:

• style — 'list' for <li>, otherwise uses separator
• use_desc_for_title — Use description as link title
• feed / feed_image / feed_type — Add RSS feed link
• show_count — Append post count
• current_category — ID(s) of current category for CSS classes
• separator — Text between categories when not list style

Output formats:

List style ($args['style'] === 'list'):

<li class="cat-item cat-item-5 current-cat">
    <a href="/category/news/" aria-current="page">News</a> (42)

Separator style:

    <a href="/category/news/">News</a> |

Default:

    <a href="/category/news/">News</a><br />

end_el()

Closes the list item (list style only).

public function end_el( &$output, $data_object, $depth = 0, $args = [] )

Output:

</li>

CSS Classes

Applied to <li> elements:

Usage Example

// Direct usage
$walker = new Walker_Category();
$categories = get_terms( [
    'taxonomy'   => 'category',
    'hide_empty' => true,
] );

echo '<ul>';
echo $walker->walk( $categories, 0, [
    'style'             => 'list',
    'show_count'        => true,
    'use_desc_for_title' => true,
    'current_category'  => get_queried_object_id(),
] );
echo '</ul>';

// Via wp_list_categories() with custom walker
wp_list_categories( [
    'walker' => new My_Custom_Category_Walker(),
    'title_li' => '',
] );

Extending

class My_Category_Walker extends Walker_Category {
    public function start_el( &$output, $category, $depth = 0, $args = [], $current = 0 ) {
        // Add icon before category name
        $icon = get_term_meta( $category->term_id, 'icon', true );
        $output .= '<li>';
        $output .= '<a href="' . esc_url( get_term_link( $category ) ) . '">';
        if ( $icon ) {
            $output .= '<span class="icon">' . esc_html( $icon ) . '</span> ';
        }
        $output .= esc_html( $category->name );
        $output .= '</a>';
    }
}

Related

• wp_list_categories() — Main function using this walker
• Walker_CategoryDropdown — Dropdown version
• list_cats filter — Modify category name
• category_css_class filter — Modify CSS classes