Show branches or levels of your menu in a widget, or in content using a shortcode, with full customisation.
NB. Version 2 documentation is here.
There are quite a few options, which makes the widget settings box very long. I have therefore grouped most of the options into collapsible logical sections (with remembered state once saved).
The associated SHORTCODE PARAMETERS are documented under Installation.
Set the title for your widget.
Prevents the entered
Title being displayed in the front-end widget output.
In the Widgets admin page, I find it useful to still be able to see the
Title in the sidebar when the widget is closed, but I
don't necessarily want that
Title to actually be output when the widget is displayed at the front-end. Hence this checkbox.
Select Menu select
Choose the appropriate menu from the dropdown list of Custom Menus currently defined in your WordPress application. The first one available (alphabetically) is already selected for you by default.
Filters are applied in the order they are presented.
Level radio (default On) & select
Filters by level within the selected menu, starting at the level selected here. This is the default setting for a new widget instance, which, if left alone and with all other options at their default, will show the entire selected menu.
Example : If you wanted to show all the options that were at level 3 or below, you could check this radio and set the select to "3".
Branch radio & select
Filters by branch, with the head item of the branch being selected from the dropdown. The dropdown presents all the items from the selected menu, plus a "Current Item" option (the default). Selecting "Current Item" means that the head item of the branch is the current menu item (as indicated by WordPress), provided, of course, that the current menu item actually corresponds to a menu item from the currently selected menu!
Items radio & textbox
Filters by the menu items that you specifically pick (by menu item id, as a comma-separated list). The simplest way to get your list of ids is to use the "assist", and [un]check the green tick box at the right hand side of each depicted menu item that you want. Alternatively, just type your list of ids into the box.
If the id is appended with a '+', eg. '23+', then all the item's descendants will also be included.
Example : If you only wanted to show, say, 5 of your many available menu items, and those 5 items are not in one handy branch of the menu, then you might want to use this option.
Example : If your menu has 6 root branches - "A" thru to "F" - and you were only interested in branches "B" (id of, say, 11) and
"E" (id of, say, 19), you could set
Items to be "11+,19+", which would include "B" with all its descendants, and "E" with all its
Secondary Filter (not applicable to an
Starting at select
This is only applicable to a
Branch filter and it allows you to shift the starting point of your output within the confines
of the selected branch. By default it is set to the selected branch item itself, but it can be changed to a relative of the branch item (eg.
parent, grandparent, children, etc) or to an absolute, fixed level within the branch containing the selected branch item (eg. the root
level item for the branch, or one level below the branch's root item, etc).
Example : If you wanted the entire "current" branch then, with
Branch set to "Current Item", you might set
Starting at to "1 (root)".
Alternatively, if you wanted the children of the current menu item then
Starting at could be set to "+1 (children)".
Item, if possible radio (default On)
This is the default filter mechanism whereby, if
Starting at can only result in a single item (ie. it is the branch item itself, or
an ancestor thereof) then only that item and its descendants are considered for filtering.
Changes the default filter mechanism such that if
Starting at results in the selection of the branch item or one of its ancestors,
then all siblings of that resultant item are also included in the secondary filtering process.
Example : If Joe and Fred are siblings (ie. they have a common parent) and Joe is the selected branch item - with
Starting at set
to Joe - then the secondary filter would normally only consider Joe and its descendants. However, if
Level was enabled instead of
Item, then both Joe and Fred, and all their descendants, would be considered for filtering.
Note that there is one exception, and that is that if
Starting at results in a root-level item, then
Allow all Root Items must
be enabled in order to allow the other sibling root items to be added into the filter process.
Allow all Root Items checkbox
In the right conditions - see
Level above - this allows sibling root items to be considered for secondary filtering.
For Depth select
This the number of levels of the menu structure that will be considered for inclusion in the final output (in complete ignorance of any subsequent Inclusions or Exclusions).
The first level of output is the starting level, regardless of
how that starting level is determined (see
Starting at and
Relative to Current Item options). So if you ask
for a Depth of 1 level, you get just the starting level; if you ask for a Depth of 2, you get the starting level and
the one below it.
Relative to Current Item checkbox
For Depth (above) is relative to the first item found, but this may be overridden to be relative to the
current menu item if
For Depth is not unlimited and the current menu item can found within the selected menu.
If the current menu item is not within the selected menu then it falls back to being relative to the first item found.
Please note that the current item must also be within the constraints set by the
Starting at option. In other words, if
current item is above the
Starting at level in the menu structure then it will not be used to alter the determination of
These allow certain other items to be added to the output from the secondary filters.
The first 3 are only applicable to a
Branch filter. Please note that they only come into effect when the
Branch filter item is at
or below the
Starting at level, and do not include any items that would break the depth limit set in the Secondary Filter options.
Branch Ancestors select
Include any ancestors (parent, grandparent, etc) of the items selected as the
Ancestors can be set to go up to an absolute level, or to go up a certain number of levels relative to the
Branch filter item.
... with Siblings select
In conjunction with
Branch Ancestors, also include all siblings of those ancestors.
As with Ancestors, their siblings can be set to go up to an absolute level, or to go up a certain number of levels relative
Branch filter item. Note that while it is possibe to set a larger range for siblings than ancestors, the final output
is limited by
Branch Ancestors setting.
Branch Siblings checkbox
Include any siblings of the item selected as the
Branch filter (ie. any items at the same level and within
the same branch as the
This allows an entire level of items to be included, optionally also including all levels either above or below it.
This replaces the
All Root Items checkbox (pre v3.0.4), which only allowed for the inclusion of the root level items.
Item Ids textbox
This is a comma-separated list of the ids of menu items that you do not want to appear in the final output. The simplest way to get your list of ids is to use the "assist", and [un]check the red cross box at the left hand side of each depicted menu item. Alternatively, just type your list of ids into the box.
If the id is appended with a '+', eg. '23+', then all the item's descendants will also be excluded.
Example : If you wanted to show the entire "A" branch, with the sole exception of one grandchild of "A", say "ABC", then you could
Branch to "A", and
Exclusions to the id of the "ABC" item.
Example : If you have a menu with 4 root items - "A", "B", "C" & "D" - and you wanted to show all items, with descendants, for all bar
the "C" branch, then you could set
Level to "1 (root)" and
Exclusions to, say, "12+", where "12" is the menu item id for "C" and
the "+" indicates that all the descendants of "C" should also be excluded.
This allows an entire level of items to be excluded, optionally also excluding all levels either above or below it.
Current Item is in select
This allows you to specify that there only be any output shown when/if the current menu item is one of the menu items selected for output at a particular stage in the filter processing.
Branchitem, then if "A" was the current menu item there would be no output with this qualifier.
Branchas "A", with
Starting atset to "+1 (children)", then if "A" was the current menu item there would be no output with this qualifier.
The "If Current Item has no children" fallback gets applied at the Secondary Filter stage, and its eligibility and application are therefore determined and governed by the other Secondary Filter settings.
It only comes into play (possibly) when a
is set as "Current Item", and the
Starting at and
For Depth settings are such that the output should start at or below the current item,
and would normally include some of the current item's descendants (eg.
Starting at "the Branch",
For Depth "1 level" does not invoke
The fallback allows for the occasion when the current menu item
does not have any immediate children, and provides the ability to then switch the following options:
Starting at select
Enable the fallback, and change the
Starting at from "+1 (children)" to either
...and Include its Siblings checkbox
This will add in the siblings of the item selected above.
Note : This only adds the siblings, not the siblings' descendants! However, if the
Level radio (in Secondary Filter stage above) is
set, then all the item's siblings and their descendants will automatically be included, and [un]setting this option will have no effect.
Also note that if the fallback results in a root-level item being selected as the new
Starting at item, then the inclusion of siblings
outside the current branch depends on the setting of the
Allow all Root Items checkbox.
For Depth select
Override the current
For Depth setting. Note that any depth value set here will be relative to the current item, regardless
of the current setting of
As an example, this option may be useful in the following scenario : item A has 2 children, B and C; B is the current menu item but has no children, whereas C has loads of children/grandchildren. If you fallback to B's parent - A - with Unlimited depth set, then you will get A, B, C, and all C's dependents! You may well want to override depth to limit the output to, say, just A, B and C, by setting this fallback option to "1"? Or maybe A, B, C, and C's immediate children, by setting "2"?
The "If no Current Item can be found" fallback is new to v3.1.0. It gets applied right at the start of processing, when determining which of the menu items (if any) should be regarded as the unique "Current Item" by this widget. Under certain conditions, WordPress will mark an item as
Requires: 3.6 or higher
Compatible up to: 4.1.6
Last Updated: 2015-4-2
Active Installs: 10,000+
4 of 9 support threads in the last two months have been resolved.
Got something to say? Need help?