2026年11月12日

Personalizar el menú de navegación de WordPress con Walker_Nav_Menu

Temas y diseño

Este artículo es una edición localizada del original en japonés. Leer el original en japonés

Introducción

«Quiero controlar a mi gusto el HTML de la navegación de la cabecera», «quiero implementar menús desplegables o un menú hamburguesa», «quiero añadir iconos o insignias a los elementos del menú»: si personalizas la clase Walker_Nav_Menu, puedes controlar por completo la salida de navegación de WordPress.

Síntomas y causas

Con la salida predeterminada de wp_nav_menu() es difícil controlar las clases CSS o insertar HTML propio, y a veces no se puede crear la estructura que necesita un diseño moderno. Al extender Walker_Nav_Menu puedes personalizar por completo el HTML de salida.

Pasos para solucionarlo

Paso 1: registra los menús de navegación

// functions.php: registra las zonas de los menús de navegación
add_action( 'after_setup_theme', function() {
    register_nav_menus( [
        'primary'   => 'Navegación global',
        'footer'    => 'Navegación del pie de página',
        'mobile'    => 'Menú móvil',
        'social'    => 'Enlaces sociales',
    ] );
} );

Paso 2: muestra la navegación básica con wp_nav_menu()

// header.php: navegación global
wp_nav_menu( [
    'theme_location'  => 'primary',      // ID de la zona de menú registrada
    'container'       => 'nav',          // Elemento contenedor (false lo desactiva)
    'container_class' => 'global-nav',
    'container_id'    => 'global-nav',
    'menu_class'      => 'nav-list',
    'menu_id'         => 'nav-list',
    'echo'            => true,
    'fallback_cb'     => false,          // No muestra nada si no hay menú configurado
    'depth'           => 3,              // Profundidad de niveles del menú que se muestran
    'items_wrap'      => '<ul id="%1$s" class="%2$s" role="list">%3$s</ul>',
] );

Paso 3: implementa una salida personalizada con Walker_Nav_Menu

// functions.php: NavWalker personalizado
class My_Nav_Walker extends Walker_Nav_Menu {

    // Etiqueta de apertura del elemento de menú
    public function start_el( &$output, $item, $depth = 0, $args = null, $id = 0 ) {
        $classes   = empty( $item->classes ) ? [] : (array) $item->classes;
        $classes[] = 'nav-item';
        $classes[] = 'menu-item-' . $item->ID;

        // Elemento de menú de la página actual
        if ( in_array( 'current-menu-item', $classes, true ) ) {
            $classes[] = 'is-active';
        }

        // Si hay submenú
        $has_children = in_array( 'menu-item-has-children', $classes, true );
        if ( $has_children ) {
            $classes[] = 'has-dropdown';
        }

        $class_str = implode( ' ', array_filter( array_unique( $classes ) ) );

        $output .= '<li class="' . esc_attr( $class_str ) . '">';

        // Atributos de la etiqueta de enlace
        $atts           = [];
        $atts['href']   = ! empty( $item->url ) ? $item->url : '#';
        $atts['title']  = ! empty( $item->attr_title ) ? $item->attr_title : '';
        $atts['target'] = ! empty( $item->target ) ? $item->target : '';
        $atts['rel']    = ! empty( $item->xfn ) ? $item->xfn : '';

        // La página actual lleva aria-current
        if ( in_array( 'current-menu-item', $classes, true ) ) {
            $atts['aria-current'] = 'page';
        }

        // Si hay submenú, aria-haspopup
        if ( $has_children ) {
            $atts['aria-haspopup'] = 'true';
            $atts['aria-expanded'] = 'false';
        }

        $atts = apply_filters( 'nav_menu_link_attributes', $atts, $item, $args, $depth );

        $attrs_str = '';
        foreach ( $atts as $attr => $value ) {
            if ( is_scalar( $value ) && '' !== $value ) {
                $attrs_str .= ' ' . $attr . '="' . esc_attr( $value ) . '"';
            }
        }

        $title = apply_filters( 'the_title', $item->title, $item->ID );

        $output .= '<a' . $attrs_str . '>';
        $output .= '<span class="nav-label">' . esc_html( $title ) . '</span>';

        // Si hay submenú, botón de despliegue
        if ( $has_children && 0 === $depth ) {
            $output .= '<button class="dropdown-toggle" aria-label="Abrir submenú">'
                     . '<svg viewBox="0 0 12 8" width="12" aria-hidden="true"><path d="M1 1l5 5 5-5" stroke="currentColor" stroke-width="2" fill="none"/></svg>'
                     . '</button>';
        }

        $output .= '</a>';
    }

    // Etiqueta de apertura del submenú
    public function start_lvl( &$output, $depth = 0, $args = null ) {
        $output .= '<ul class="dropdown-menu" role="list">';
    }

    // Etiqueta de cierre del submenú
    public function end_lvl( &$output, $depth = 0, $args = null ) {
        $output .= '</ul>';
    }
}

// Muestra el menú con el Walker
wp_nav_menu( [
    'theme_location' => 'primary',
    'container'      => 'nav',
    'container_class' => 'global-nav',
    'walker'         => new My_Nav_Walker(),
] );

Paso 4: implementa el menú desplegable con CSS

/* Navegación global */
.global-nav {
    position: relative;
}

.nav-list {
    display: flex;
    align-items: center;
    gap: 0;
    list-style: none;
    margin: 0;
    padding: 0;
}

.nav-item {
    position: relative;
}

.nav-item > a {
    display: flex;
    align-items: center;
    gap: 4px;
    padding: 1rem 1.25rem;
    color: #1d2327;
    text-decoration: none;
    font-weight: 500;
    font-size: 0.9rem;
    transition: color 0.2s;
    white-space: nowrap;
}

.nav-item > a:hover,
.nav-item.is-active > a {
    color: #2271b1;
}

/* Menú desplegable */
.dropdown-menu {
    position: absolute;
    top: 100%;
    left: 0;
    min-width: 220px;
    background: #fff;
    border: 1px solid #dcdcde;
    border-radius: 4px;
    box-shadow: 0 4px 12px rgba(0,0,0,0.12);
    list-style: none;
    margin: 0;
    padding: 0.5rem 0;
    opacity: 0;
    visibility: hidden;
    transform: translateY(-8px);
    transition: opacity 0.2s, transform 0.2s, visibility 0.2s;
    z-index: 100;
}

.nav-item.has-dropdown:hover > .dropdown-menu,
.nav-item.has-dropdown:focus-within > .dropdown-menu,
.nav-item.has-dropdown[data-open="true"] > .dropdown-menu {
    opacity: 1;
    visibility: visible;
    transform: translateY(0);
}

.dropdown-menu li a {
    display: block;
    padding: 0.6rem 1.25rem;
    color: #1d2327;
    text-decoration: none;
    font-size: 0.875rem;
    transition: background 0.15s;
}

.dropdown-menu li a:hover {
    background: #f0f6fc;
    color: #2271b1;
}

/* Botón hamburguesa */
.hamburger-btn {
    display: none;
    flex-direction: column;
    gap: 5px;
    background: none;
    border: none;
    cursor: pointer;
    padding: 8px;
}

.hamburger-btn span {
    display: block;
    width: 24px;
    height: 2px;
    background: #1d2327;
    transition: transform 0.3s, opacity 0.3s;
}

@media (max-width: 768px) {
    .hamburger-btn { display: flex; }

    .nav-list {
        display: none;
        flex-direction: column;
        position: fixed;
        top: 0;
        right: 0;
        width: 280px;
        height: 100vh;
        background: #fff;
        padding: 4rem 1.5rem 2rem;
        box-shadow: -4px 0 20px rgba(0,0,0,0.15);
        overflow-y: auto;
        z-index: 1000;
    }

    .nav-list.is-open { display: flex; }
}

Paso 5: controla el menú hamburguesa y el desplegable con JavaScript

// js/navigation.js
(function() {
    const btn    = document.querySelector('.hamburger-btn');
    const menu   = document.getElementById('nav-list');
    if (!btn || !menu) return;

    // Abre y cierra el menú hamburguesa
    btn.addEventListener('click', function() {
        const isOpen = menu.classList.toggle('is-open');
        btn.setAttribute('aria-expanded', isOpen);
        btn.setAttribute('aria-label', isOpen ? 'Cerrar el menú' : 'Abrir el menú');
        document.body.style.overflow = isOpen ? 'hidden' : '';
    });

    // Se cierra con la tecla Esc
    document.addEventListener('keydown', function(e) {
        if (e.key === 'Escape' && menu.classList.contains('is-open')) {
            menu.classList.remove('is-open');
            btn.setAttribute('aria-expanded', 'false');
            document.body.style.overflow = '';
            btn.focus();
        }
    });

    // Manejo del desplegable con el teclado
    document.querySelectorAll('.dropdown-toggle').forEach(function(toggle) {
        toggle.addEventListener('click', function(e) {
            e.preventDefault();
            const parent = toggle.closest('.has-dropdown');
            const isOpen = parent.getAttribute('data-open') === 'true';
            parent.setAttribute('data-open', !isOpen);
            toggle.setAttribute('aria-expanded', !isOpen);
        });
    });

    // Se cierra al hacer clic fuera del menú
    document.addEventListener('click', function(e) {
        if (!menu.contains(e.target) && !btn.contains(e.target)) {
            menu.classList.remove('is-open');
            btn.setAttribute('aria-expanded', 'false');
            document.body.style.overflow = '';
        }
    });
})();

Precauciones

Si extiendes Walker_Nav_Menu, llama siempre a apply_filters('nav_menu_link_attributes', ...) dentro de start_el(). Es un hook necesario para que los plugins puedan añadir atributos a los enlaces.
Para que el menú desplegable funcione con el teclado y los lectores de pantalla, configura correctamente aria-haspopup y aria-expanded.
Si estableces fallback_cb de wp_nav_menu() en false, no se muestra nada cuando no hay ningún menú configurado. Por defecto, recurre a wp_page_menu().

Resumen

La personalización del menú de navegación se organiza así: «registra las zonas con register_nav_menus() → muestra la salida básica con wp_nav_menu() → hereda de Walker_Nav_Menu para controlar por completo la estructura HTML → implementa con CSS el menú desplegable y las animaciones → con JS, gestiona la apertura y el cierre del menú hamburguesa y la accesibilidad». Artículos relacionados: Cómo personalizar las zonas de widgets de WordPress y Cómo implementar migas de pan en WordPress.

¿Dudas sobre WordPress? Quien publica este sitio está en Japón y responde en japonés. Contacto (en japonés)