Creates an HTML list of hierarchical pages.

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

Class Synopsis

class Walker_Page extends Walker {
    public $tree_type = 'page';
    public $db_fields = [
        'parent' => 'post_parent',
        'id'     => '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' => 'post_parent',  // WP_Post->post_parent
    'id'     => 'ID',           // WP_Post->ID
];

Methods

start_lvl()

Opens a child page list container.

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

Output:

<ul class='children'>

Item spacing: If $args['item_spacing'] === 'preserve', includes tabs and newlines for formatting.

end_lvl()

Closes the child page list container.

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

Output:

</ul>

start_el()

Outputs a page list item with link.

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

Args used:

• item_spacing — 'preserve' for formatted output
• pages_with_children — Array keyed by page IDs that have children
• link_before / link_after — Content inside <a> before/after title
• show_date — 'modified' or truthy for post date

Output:

<li class="page_item page-item-5 current_page_item page_item_has_children">
    <a href="/about/" aria-current="page">About</a>

end_el()

Closes the list item.

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

Output:

</li>

CSS Classes

Applied to <li> elements:

Link Attributes

The <a> element includes:

• href — Page permalink
• aria-current="page" — When viewing this page

Usage Example

// Direct usage
$walker = new Walker_Page();
$pages = get_pages( [
    'sort_column' => 'menu_order',
    'sort_order'  => 'ASC',
] );

echo '<ul class="page-list">';
echo $walker->walk( $pages, 0, [
    'item_spacing'  => 'preserve',
    'link_before'   => '<span>',
    'link_after'    => '</span>',
    'show_date'     => true,
    'date_format'   => 'F j, Y',
] );
echo '</ul>';

// Via wp_list_pages()
wp_list_pages( [
    'title_li'    => '',
    'sort_column' => 'menu_order',
    'walker'      => new My_Custom_Page_Walker(),
] );

Extending

class My_Page_Walker extends Walker_Page {
    public function start_el( &$output, $page, $depth = 0, $args = [], $current = 0 ) {
        $classes = [ 'page-item', 'page-item-' . $page->ID ];
        
        if ( $page->ID === $current ) {
            $classes[] = 'is-active';
        }
        
        // Add thumbnail
        $thumb = get_the_post_thumbnail( $page->ID, 'thumbnail' );
        
        $output .= sprintf(
            '<li class="%s"><a href="%s">%s%s</a>',
            esc_attr( implode( ' ', $classes ) ),
            esc_url( get_permalink( $page->ID ) ),
            $thumb,
            esc_html( $page->post_title )
        );
    }
}

Empty Title Handling

Pages without titles display as:

#123 (no title)

This is wrapped with the the_title filter.

Related

• wp_list_pages() — Main function using this walker
• Walker_PageDropdown — Dropdown version
• page_css_class filter — Modify CSS classes
• page_menu_link_attributes filter — Modify link attributes