wp_update_menu_item: update a menu item

Changes an existing menu item, preserving what you do not pass.

Arguments

Permissions

Allow content writes open, and edit_theme_options.

It preserves what you omit

The tool reads the existing item first and carries forward its title, URL, parent, object type and object ID unless you supply replacements.

That makes a narrow edit genuinely narrow: passing only title renames the item and leaves it where it is, pointing where it pointed.

It is a better-behaved update than most in the server, and it means you can safely change one property without restating the rest.

Changing the parent moves the subtree

Passing parent re-parents the item — and its children move with it.

Because the item listing does report parent and order, you can see the structure before you change it. Do:

Show me the items in menu 3 with their IDs and parents. Then move item 88 under item 42.

Setting parent to 0 promotes an item to the top level.

Re-pointing an item

Two ways, and they behave differently afterwards:

Pass url to set a literal address. WordPress will not maintain it, so it breaks if the target's slug changes.

Pass object and object_id together to link it to a WordPress record. WordPress keeps the URL correct as the target changes.

Converting a fragile custom link into a maintained object link is one of the more useful things this tool does, and it is worth doing whenever you touch an item that points at your own content.

The label is independent of the target

A menu item's title does not update when the linked page's title changes. They are separate values.

So a page renamed from "Services" to "What we do" keeps a menu entry saying "Services" until someone changes it here. Worth checking after any page rename. See wp_update_page.

The dry run

Reports what it would write. Because the tool merges with existing values, the dry run is the clearest way to confirm that the merge produced what you expect — particularly when changing the parent.

After writing

Menus are on every page, so check visually:

1. Open the site; confirm the label, position and dropdown.
2. Click the item.
3. Check mobile.
4. Purge the cache.

Multilingual sites

Each language's menu is separate. Renaming an item in one language leaves the others unchanged, which produces a site whose navigation says different things depending on the language — usually not deliberately.

Common problems

Related

• wp_get_menu_items — read before writing
• wp_create_menu_item
• wp_reorder_menu_items