wp_reorder_menu_items: reorder menu items
Sets the order of menu items by listing their IDs in the sequence you want.
Arguments
| Argument | Required | Meaning |
|---|---|---|
menu_id |
Yes | The menu |
items |
Yes | Item IDs in the intended order |
dry_run |
No | Report without writing |
Permissions
Allow content writes open, and edit_theme_options.
How it works
Each item in the array is assigned a position matching its place in the list — first, second, third, and so on. The order of the array is the resulting order.
Pass the complete list
The tool only touches the items you name. Any item you omit keeps whatever position it had.
That is the property to plan around: a partial list produces a mixture of new and old positions, which can leave two items sharing a position and an order that looks arbitrary.
Read the menu first and send every item:
Show me the items in menu 3 with their IDs and current order. Then set this order: 12, 45, 88, 91, 103.
State the result, not a move
An instruction like "move Contact up one" depends on the assistant's understanding of the current order — which is exactly the thing you should not leave to inference.
Give the intended end state as a full sequence. It is unambiguous, and it is verifiable against the listing you just read.
Hierarchy is separate from order
This tool sets position only. It does not change which item is a child of which.
To restructure the hierarchy, use wp_update_menu_item with parent. A common sequence is: re-parent the items that need moving, then reorder within their new level.
Note that ordering applies within a level. Reordering a mixed list of top-level items and sub-items produces positions that only make sense once you account for the hierarchy — which is another reason to read parent alongside order before starting.
The dry run
Returns the list it would apply. Worth checking against the listing you read, because a transposed ID in a long sequence is easy to make and hard to spot afterwards.
What it returns
How many items were updated. Compare that against the number you sent — a mismatch means some IDs were not valid.
After reordering
Menus are on every page:
- Open the site and read the menu left to right.
- Open each dropdown.
- Check mobile, where order can matter more because everything is vertical.
- Purge the cache.
Multilingual sites
Each language's menu is ordered independently. Reordering one leaves the others as they were, and navigation that reads in a different order per language is usually unintentional.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | Content write gate closed |
pom_ai_mcp_forbidden |
No edit_theme_options |
| The order is partly wrong | An incomplete list; omitted items kept their old positions |
| Two items appear interchangeable | They ended up with the same position |
| Sub-items moved oddly | Ordering is within a level; check parent |
| Fewer updates than IDs sent | Some IDs were not valid menu items |
| The site shows the old order | Cache not purged |
Related
wp_get_menu_items— read the current order firstwp_update_menu_itemfor hierarchy- Edit a navigation menu