Home » Navigation

Navigation

Boilerplate navigation is built around WordPress menu locations, a Bootstrap 5-compatible navwalker, navbar layout partials, PHP-powered special menu items, and SASS styling scoped to the main navbar system.

Menu Registration

Navbar menu locations are registered conditionally based on the active theme configuration. Boilerplate supports separate left and right navbar menus so project navigation can be split cleanly across the navbar.

File: lib/menus.php
Menu locations: bp-navbar-left, bp-navbar-right
Config: BP_NAVBAR_LEFT_MENU_ENABLED, BP_NAVBAR_RIGHT_MENU_ENABLED

Navbar Partial

The main navbar markup lives in the navbar layout partial. This file renders the brand area, Bootstrap collapse button, left menu, right menu, and navbar action hooks.

File: partials/layout/navbar.php
Loaded by: partials/layout/top.php when BP_NAVBAR_ENABLED is enabled.

Use this for: navbar structure, brand placement, collapse layout, menu rendering, and navbar-level hook locations.

Bootstrap 5 Navwalker

Boilerplate uses a theme-owned Bootstrap 5-compatible WordPress navwalker. The walker converts WordPress menu output into Bootstrap-compatible navbar and dropdown markup.

File: lib/bootstrap_navwalker.php
Class: WP_Bootstrap_Navwalker
Used by: wp_nav_menu() calls in partials/layout/navbar.php
Config: BP_NAVBAR_DROPDOWNS_ENABLED

Dropdowns, Headers, Dividers, and Item Text

The navwalker supports Bootstrap dropdown behavior and recognizes menu item classes that change how submenu items render.

File: lib/bootstrap_navwalker.php

  • dropdown-header – renders submenu item as a dropdown header
  • dropdown-divider – renders submenu item as a divider
  • dropdown-item-text – renders submenu item as non-link text
  • disabled – marks an item as disabled
  • visually-hidden – supports screen-reader-only menu text

Use this for: menu editor-controlled dropdown structure without hardcoding dropdown markup in templates.

Left and Right Navbar Menus

The left navbar menu uses Bootstrap’s me-auto alignment class. The right navbar menu uses ms-auto. This allows primary navigation and utility navigation to be managed as separate WordPress menus.

File: partials/layout/navbar.php
Left menu class: navbar-nav me-auto
Right menu class: navbar-nav ms-auto

Related style support: assets/sass/parent_theme/bootstrap/overrides.scss handles right-aligned dropdown positioning for .ms-auto nav menus.

Special Menu Items

Special navbar controls are PHP-powered WordPress Custom Link menu items. Add the supported hash URL in the WordPress menu editor and Boilerplate converts the item into the correct control.

File: lib/navbar_special_items.php

Use this for: admin-placeable navbar controls without editing navbar templates.

Color Mode Toggle Menu Items

Color mode toggles can be placed in either navbar menu using a WordPress Custom Link. Boilerplate converts the menu item into a light/dark mode toggle when color mode toggles are enabled and the color mode is not forced.

File: lib/navbar_special_items.php
Related JS: assets/js/color_mode.js

Supported Custom Link URLs:

  • #bp-color-mode-toggle – icon-only color mode toggle
  • #bp-color-mode-toggle-with-text – icon and text color mode toggle

Config: BP_COLOR_MODE_TOGGLE_ENABLED, BP_COLOR_MODE

Navbar Search Menu Items

Navbar search is admin-placeable through special menu items. Add the supported Custom Link URL to a navbar menu and Boilerplate renders the navbar search form through the shared search form system.

Primary file: lib/navbar_special_items.php
Partial: partials/layout/navbar_search.php
Function: bp_navbar_search_form()

Supported Custom Link URLs:

  • #bp-navbar-search – icon-only navbar search
  • #bp-navbar-search-with-text – search item with visible text

Use this for: placing search in the navbar through WordPress admin menus instead of hardcoding it into the navbar partial.

Navbar Styling

Main navbar styling is owned by the layout navbar stylesheet. This file controls navbar colors, Bootstrap navbar CSS variables, link states, dropdown colors, brand behavior, toggler styling, and light/dark navbar theming.

File: assets/sass/parent_theme/layout/navbar.scss

Use this for: visual navbar behavior, navbar link colors, dropdown styling, brand styling, toggler styling, and color-mode-aware navbar presentation.

Configuration

  • BP_NAVBAR_ENABLED – enables/disables the navbar
  • BP_NAVBAR_CLASSES – controls the classes applied to the main navbar element
  • BP_NAVBAR_INNER_BS5_CONTAINER_ENABLED – wraps navbar content in a Bootstrap container when enabled
  • BP_NAVBAR_BRAND_IMAGE_ENABLED – enables the brand image
  • BP_NAVBAR_BRAND_TEXT_ENABLED – enables the brand text
  • BP_NAVBAR_LEFT_MENU_ENABLED – enables the left navbar menu location
  • BP_NAVBAR_RIGHT_MENU_ENABLED – enables the right navbar menu location
  • BP_NAVBAR_DROPDOWNS_ENABLED – enables dropdown depth support through the navwalker

Files

  • config.php – navbar feature flags and navbar configuration constants
  • lib/menus.php – WordPress menu location registration
  • lib/bootstrap_navwalker.php – Bootstrap 5-compatible menu walker
  • lib/navbar_special_items.php – color mode and search special menu item handling
  • partials/layout/navbar.php – main navbar template
  • partials/layout/navbar_search.php – navbar search partial
  • partials/layout/top.php – loads the navbar when enabled
  • assets/sass/parent_theme/layout/navbar.scss – main navbar styling
  • assets/sass/parent_theme/bootstrap/overrides.scss – Bootstrap navbar/dropdown normalization
  • assets/js/color_mode.js – client-side color mode toggle behavior

Rule of Thumb

Use config.php to enable or disable navbar behavior. Use WordPress menus to manage navbar content. Use lib/bootstrap_navwalker.php for Bootstrap 5 menu markup behavior. Use lib/navbar_special_items.php for admin-placeable navbar controls. Use assets/sass/parent_theme/layout/navbar.scss for navbar presentation.

© 2026 Boilerplate