Using WordPress ‘wp_list_pages’ PHP filter

by

The wp_list_pages WordPress PHP filter modifies the HTML output of the pages to list.

Usage

add_filter( 'wp_list_pages', 'your_custom_function', 10, 3 );

function your_custom_function( $output, $parsed_args, $pages ) {
    // your custom code here
    return $output;
}

Parameters

  • $output (string) – The HTML output of the pages list.
  • $parsed_args (array) – An array of page-listing arguments. See wp_list_pages() for information on accepted arguments.
  • $pages (WP_Post[]) – Array of the page objects.

More information

See WordPress Developer Resources: wp_list_pages

Examples

Add a custom class to all page links

This example adds a custom class to all page links in the list.

add_filter( 'wp_list_pages', 'add_custom_class_to_page_links', 10, 3 );

function add_custom_class_to_page_links( $output, $parsed_args, $pages ) {
    $output = str_replace( '<a ', '<a class="your-custom-class" ', $output );
    return $output;
}

Hide a specific page from the list

This example hides a specific page (ID: 42) from the list of pages.

add_filter( 'wp_list_pages', 'hide_specific_page', 10, 3 );

function hide_specific_page( $output, $parsed_args, $pages ) {
    $page_to_remove = 42;
    $output = preg_replace( '/<li class="page_item page-item-' . $page_to_remove . '">.*?<\/li>/', '', $output );
    return $output;
}

Wrap page list items in a custom HTML tag

This example wraps each page list item in a <span> tag.

add_filter( 'wp_list_pages', 'wrap_page_list_items', 10, 3 );

function wrap_page_list_items( $output, $parsed_args, $pages ) {
    $output = preg_replace( '/<li(.*?)>/', '<li$1><span>', $output );
    $output = str_replace( '</li>', '</span></li>', $output );
    return $output;
}

Add an icon before each page title

This example adds a custom icon (e.g., Font Awesome) before each page title.

add_filter( 'wp_list_pages', 'add_icon_before_page_title', 10, 3 );

function add_icon_before_page_title( $output, $parsed_args, $pages ) {
    $icon = '<i class="fas fa-star"></i> ';
    $output = preg_replace( '/(<a.*?>)/', '$1' . $icon, $output );
    return $output;
}

Add an “active” class to the current page

This example adds an “active” class to the current page list item.

add_filter( 'wp_list_pages', 'add_active_class_to_current_page', 10, 3 );

function add_active_class_to_current_page( $output, $parsed_args, $pages ) {
    global $post;
    $current_page_id = $post->ID;
    $output = preg_replace( '/<li class="page_item page-item-' . $current_page_id . '">/', '<li class="page_item page-item-' . $current_page_id . ' active">', $output );
return $output;
}

Add custom data attribute to page links

This example adds a custom data attribute to each page link in the list. 

 add_filter( 'wp_list_pages', 'add_data_attribute_to_page_links', 10, 3 );

function add_data_attribute_to_page_links( $output, $parsed_args, $pages ) {
$output = preg_replace( '/<a(.*?)>/', '<a$1 data-custom="your-data">', $output );
return $output;
}


Add a "no-follow" attribute to external page links


This example adds a "no-follow" attribute to external page links in the list.


add_filter( 'wp_list_pages', 'add_nofollow_to_external_links', 10, 3 );

function add_nofollow_to_external_links( $output, $parsed_args, $pages ) {
    $home_url = home_url();
    $output = preg_replace( '/<a href="(?!' . preg_quote( $home_url, '/' ) . ')(.*?)>/', '<a href="$1" rel="nofollow">', $output );
    return $output;
}



Replace the default list element with a custom element


This example replaces the default <li> element with a custom <div> element for each page in the list.


add_filter( 'wp_list_pages', 'replace_list_element_with_custom_element', 10, 3 );

function replace_list_element_with_custom_element( $output, $parsed_args, $pages ) {
    $output = preg_replace( '/<li(.*?)>/', '<div$1>', $output );
    $output = str_replace( '</li>', '</div>', $output );
    return $output;
}



Add the page excerpt below the page title


This example adds the page excerpt below each page title in the list.


add_filter( 'wp_list_pages', 'add_excerpt_below_page_title', 10, 3 );

function add_excerpt_below_page_title( $output, $parsed_args, $pages ) {
    foreach ( $pages as $page ) {
        $excerpt = apply_filters( 'the_excerpt', $page->post_excerpt );
        $output = str_replace( '</a></li>', '</a><p>' . $excerpt . '</p></li>', $output );
    }
    return $output;
}