In my last post, I covered How To Use WordPress Custom Menus on your blog – so today we’ll take it a step further and discuss how to add custom menus into a theme – either a new one you’re building on your own or an existing one that you’d like to add this function to.
There are two primary steps to the process of implementing WordPress Custom Menus. First we need to register the menu location(s) within the WordPress database – this is done in the
functions.php file of your theme.
From there we need add the function that actually displays the menu for you – so the file you need to open here will depend on what you are trying to accomplish. The most common options are going to be either
footer.php (or both).
Registering WordPress Custom Menus
The first step in is going to be telling WordPress what menu locations are available. WordPress will then take that information and display it in the “Theme Locations” module of the “Menus” screen in the WordPress dashboard. You, or your theme’s users, will then be able to select their custom menus from a dropdown list for each location.
To start, open
functions.php in your favorite text editor. You can register your menus at the bottom of the page, just before the closing of the
PHP tag, but I usually like to place mine just after the sidebar registration.
If you’re registering just a single menu, you can use the function
register_nav_menu(); For multiple menus you would use
register_nav_menus();. Makes sense, right?
When adding this function in, you need to provide values for two arguments. First off you have the location, which is basically a slug – similar to those used the the URLs of posts and pages. The difference here is you don’t really see this value, it’s just how WordPress keeps track of your menu locations within the database.
The second argument for the function is the description. This is the name that shows up in the “Theme Locations” section of the “Menus” screen – so it should be something that will make it clear to you, or your theme’s users where that menu actually shows up.
Here’s an example of
register_nav_menu() in action. You can copy and paste this into your
functions.php file and change the arguments if you’d like.
register_nav_menu('main_nav','Bottom Of Header Navigation');
…and that’s that. A couple of things to notice here: first off I didn’t use any
PHP tags, because we’re doing all of this within the tags that are already present in
functions.php. If you run into trouble at this point, make sure your function falls within the
Second, each of the two arguments are encased in quotes, and they are separated by a comma.
Here’s and example of registering multiple menus with
register_nav_menus(); (yes, the only real difference is the pluralization of the word menu):
'header_topnav' => 'Top of Header',
'header_bottomnav' => 'Bottom of Header',
'footer_nav' => 'Right Side of Footer'
The structure here is a little more complex because we are using an array to store the different menus. If you aren’t familiar with arrays, don’t worry – they’re just a way to store multiple pieces of data all together.
To break this chunk of code down, we’re opening the function on line one, then opening an array within the function on line two. Lines three, four, and five are the location and description pairs that we used in the last example. This time, notice that the location and description are separated by an arrow, (an equals sign and right angled bracket) rather than a comma. The commas are used to separate the different values of the array.
Line six closes the array with a right parenthesis, and line seven closes the function the same way, followed by a semi colon.
Now, if you take a look at the “Menus” screen of the dashboard, you’ll see your newly registered menu(s) listed under “Theme Locations.” All we have to do now is tell your theme when and how to display your menu and we’re all done!
Displaying WordPress Custom Menus
The next step is going to be opening the file that will display your menu – this will vary from one situation to the next but most of the time it’ll probably be
If you’re modifying an existing theme, you’re going to want to either replace whatever menu is already in the space you want to use, or you’ll need to create a space if you’re just adding a new menu.
Now, to display a menu, we’ll be using the
wp_nav_menu(); function. This function doesn’t actually require any arguments, as it has a series of fallbacks that it uses based on the parameters you give (or don’t give) it. Here’s how those fallbacks work.
wp_nav_menu(); first looks to see if you’ve provided a
theme_location parameter. If you have, it checks to see what menu is assigned to that location in the Menus screen of the dashboard and displays that.
If that value isn’t present, the function then checks for a menu name, slug or ID number it can use (this is called the
If a specific menu wasn’t specified, it goes on to the first custom menu it can find (the one with the lowest ID number) that has something in it.
From there the function goes into last-ditch backup mode – which defaults to a list of pages, unless you’ve specified differently.
If the final fallback doesn’t have anything to display, the menu just stays empty – but you can’t say it didn’t try!
Now that we’ve covered the function’s hierarchy of defaults, let’s look at some of the values we just discussed and how to use them. I’m not going to go into detail about all of the arguments this function can accept, just the ones that you’re most likely to want to use.
You can find a complete list of this function’s arguments in the Codex.
We’ve already covered two of the arguments –
theme_location displays the menu assigned to a certain location, and
menu displays a specific custom menu.
For basic menus, the five arguments you are most likely to need are:
These allow you to specify the class or ID of the
DIVthat the menu is wrapped in. This will allow you to style the container in your CSS
These will control the class or ID of the actual list that makes up the menu. This will allow you to style your menu in your CSS
This is where you specify how many levels of child pages you want to display in the list. entering ‘0’ will display everything, while ‘1’ only displays top level pages, and so on.
Here’s an example of this function referring to a menu location with a specific menu class and container ID. I’ve also set the depth make sure only one level of pages is shown:
'theme_location' => 'header_topnav',
'container_id' => 'above_header_nav',
'menu_class' => 'nav',
You’ll notice this function uses an array, just like
Using These Steps With An Existing Theme
If you’re modifying an existing theme, you can save yourself a lot of time by tracking down the ID and or classes of the menu and the containing
DIV (if necessary). Entering them with the arguments from above will cause your new menu to pick up the styles already built into your theme.
Unfortunately, it’s hard to give specific instructions, as the code you’re replacing will vary from one theme to the next. In a nutshell, you need to track down the menu that’s already being created – probably by something like
Since those two functions are going to be wrapped in a list element, you can grab it’s ID or class and cut that out – the function you’re adding creates it’s own list element.
Whether or not you want to delete the containing element and have it replaced by the function is going to be up to you, and depend largely on whether or not there is anything else in that element. In many cases, it’s easiest to leave that element alone and let the function create it’s own container (there is a way to prevent that container from being created, but it’s really only necessary if it messes with your CSS).
From here you should be on your way to adding custom menus to your theme – but as always, I’d love to hear your questions in the comments!