Edit a navigation menu
Menus are small, structured and highly visible. A mistake here appears on every page of the site, which makes reading before writing more valuable than usual.
The tools
| Tool | Does |
|---|---|
wp_get_menus |
List menus and their assigned locations |
wp_get_menu_items |
List the items in a menu |
wp_create_menu_item |
Add an item |
wp_update_menu_item |
Change an item |
wp_delete_menu_item |
Remove an item |
wp_reorder_menu_items |
Change the order |
Writes need Allow content writes open and edit_theme_options on the acting user — a higher bar than editing posts, which is worth knowing when choosing the acting user.
Read the whole menu first
List the menus, then show me every item in the main menu with its ID, label, URL, parent and order.
Two reasons this matters more than for other content:
- Menus are hierarchical. An item's parent determines whether it appears in the top bar or inside a dropdown, and an assistant that has not read the structure will guess.
- A menu is a whole. Changing one item's order affects the positions of others.
Also confirm which menu you are editing. A site typically has several — main, footer, mobile — and their names do not always make the assignment obvious. wp_get_menus reports the theme locations each is assigned to.
Adding an item
Add a "Maintenance" item to the main menu, pointing at page 88, as a child of "Services", positioned after "Installation".
Four things to specify: the label, the target, the parent and the position. Omitting the parent puts the item at the top level; omitting the position puts it at the end.
Check the target resolves. An item pointing at a draft page renders a link to something visitors cannot see.
Reordering
wp_reorder_menu_items changes positions. Because it operates on the set, read the current order first and state the intended result rather than a relative move:
Here is the order I want: Home, Services, Projects, About, Contact.
A relative instruction — "move Contact up one" — depends on the assistant's understanding of the current order, which is exactly the thing to avoid guessing.
Removing an item
wp_delete_menu_item removes it. This does not delete the page it pointed at; it only removes the link.
Check for children first. Removing a parent item can orphan the items beneath it, which either disappear or promote to the top level depending on the theme. Read the item list, note the children, and decide what should happen to them.
After any menu change
Menus are the one thing worth checking visually every time:
- Open the site and look at the menu, on desktop and mobile.
- Check dropdowns open and the hierarchy is what you intended.
- Check every changed link goes where it should.
- Purge the cache. Menus appear on every page, so a stale cache makes a correct change look broken.
See Clear the POM Cache.
Multilingual sites
On a site using Polylang, each language typically has its own menu assigned to the same location. Changing one does not change the others.
Read wp_get_menus and confirm which language's menu you have before editing, then plan to make the equivalent change in each language.
Common problems
| Symptom | Cause |
|---|---|
pom_ai_mcp_forbidden |
The acting user lacks edit_theme_options |
| The item appeared in the wrong place | The parent or position was not specified |
| Sub-items vanished | Their parent was removed |
| The order is not what you asked | A relative instruction was interpreted against a different starting order |
| The menu looks unchanged | Cache not purged |
| One language still shows the old menu | Each language has its own menu |