Using WordPress ‘nav_menu_item_args’ PHP filter

by

nav_menu_item_args is a WordPress PHP filter that allows you to modify the arguments for a single navigation menu item.

Usage

add_filter('nav_menu_item_args', 'your_custom_function', 10, 3);
function your_custom_function($args, $menu_item, $depth) {
    // Your custom code here
    return $args;
}

Parameters

  • $args (stdClass): An object of wp_nav_menu() arguments.
  • $menu_item (WP_Post): Menu item data object.
  • $depth (int): Depth of menu item. Used for padding.

More information

See WordPress Developer Resources: https://developer.wordpress.org/reference/hooks/nav_menu_item_args/

Examples

Add custom CSS class to menu items

Add a custom CSS class to all menu items:

add_filter('nav_menu_item_args', 'add_custom_menu_item_class', 10, 3);
function add_custom_menu_item_class($args, $menu_item, $depth) {
    $args->link_before = '<span class="custom-menu-item-class">';
    $args->link_after = '</span>';
    return $args;
}

Add a custom attribute to menu items

Add a data-depth attribute to menu items based on their depth:

add_filter('nav_menu_item_args', 'add_depth_attribute', 10, 3);
function add_depth_attribute($args, $menu_item, $depth) {
    $args->link_before = '<span data-depth="' . $depth . '">';
    $args->link_after = '</span>';
    return $args;
}

Add icons to menu items

Add icons to specific menu items based on their title:

add_filter('nav_menu_item_args', 'add_menu_icons', 10, 3);
function add_menu_icons($args, $menu_item, $depth) {
    if ($menu_item->title === 'Home') {
        $args->link_before = '<i class="fa fa-home"></i> ';
    } elseif ($menu_item->title === 'Contact') {
        $args->link_before = '<i class="fa fa-envelope"></i> ';
    }
    return $args;
}

Change menu item text color based on depth

Change the menu item text color based on the depth level:

add_filter('nav_menu_item_args', 'change_text_color_based_on_depth', 10, 3);
function change_text_color_based_on_depth($args, $menu_item, $depth) {
    if ($depth === 1) {
        $args->link_before = '<span style="color: red;">';
    } elseif ($depth === 2) {
        $args->link_before = '<span style="color: green;">';
    } else {
        $args->link_before = '<span style="color: blue;">';
    }
    $args->link_after = '</span>';
    return $args;
}

Hide menu items on mobile devices

Hide specific menu items on mobile devices:

add_filter('nav_menu_item_args', 'hide_menu_items_on_mobile', 10, 3);
function hide_menu_items_on_mobile($args, $menu_item, $depth) {
    if ($menu_item->title === 'Dashboard' || $menu_item->title === 'Profile') {
        $args->link_before = '<span class="hidden-mobile">';
        $args->link_after = '</span>';}
        return $args;
    }
}

Add custom menu item descriptions

Display custom descriptions for menu items:

add_filter('nav_menu_item_args', 'add_menu_item_description', 10, 3);
function add_menu_item_description($args, $menu_item, $depth) {
    if ($menu_item->title === 'Home') {
        $args->link_after = '<span class="menu-item-description">Welcome to our homepage</span>';
    } elseif ($menu_item->title === 'Blog') {
        $args->link_after = '<span class="menu-item-description">Read our latest articles</span>';
    } elseif ($menu_item->title === 'Contact') {
        $args->link_after = '<span class="menu-item-description">Get in touch with us</span>';
    }
    return $args;
}

Add a nofollow attribute to external menu items

Add a rel="nofollow" attribute to external menu items:

add_filter('nav_menu_item_args', 'add_nofollow_attribute', 10, 3);
function add_nofollow_attribute($args, $menu_item, $depth) {
    if (strpos($menu_item->url, 'http') === 0 && strpos($menu_item->url, home_url()) === false) {
        $args->before = '<span rel="nofollow">';
        $args->after = '</span>';
    }
    return $args;
}

Add different background colors for menu items based on depth

Add a different background color for menu items based on their depth level:

add_filter('nav_menu_item_args', 'add_background_color_based_on_depth', 10, 3);
function add_background_color_based_on_depth($args, $menu_item, $depth) {
    if ($depth === 1) {
        $args->link_before = '<span style="background-color: yellow;">';
    } elseif ($depth === 2) {
        $args->link_before = '<span style="background-color: orange;">';
    } else {
        $args->link_before = '<span style="background-color: red;">';
    }
    $args->link_after = '</span>';
    return $args;
}