Menu Icons

BuddyX Pro ships an icon picker for WordPress navigation menus. You pick an icon for a menu item in Appearance > Menus, and the theme prints it next to the menu label on the front end. Nothing needs to be installed for this to work: the code is bundled in the theme and loads on every request.

What Menu Icons Does

Menu Icons adds one control to each item in the WordPress menu editor. From that control you choose an icon type, choose an icon, and set how the icon looks next to the label.

• Adds an Icon: row inside every nav menu item panel in Appearance > Menus
• Adds an Icon column to the Screen Options panel on that same screen
• Stores the choice in a single post meta key on the menu item
• Prints the icon before or after the menu label when the menu is rendered with wp_nav_menu()
• Assigns a Font Awesome icon automatically when you add a BuddyPress item to a menu
• Falls back to a link icon for items in the Side Menu that have no icon set

The feature is a fork of the Menu Icons plugin by Kucrut, renamed to the theme. Because it is a fork, the theme actively blocks the standalone plugin. See The Menu Icons Plugin Is Blocked.

Requirements

Requirement	Notes
BuddyX Pro	Included in the theme, no separate install
WordPress menus	You need at least one menu created under Appearance > Menus
Menu Icons plugin	Must NOT be active. The theme deactivates it.

Menus rendered by a page builder or a block that does not call wp_nav_menu() will not show these icons.

Adding an Icon to a Menu Item

Step 1: Open the Menu Editor

1. Go to Appearance > Menus
2. Select the menu you want to edit, or create one
3. Add the items you want (Pages, Posts, Custom Links, BuddyPress, and so on)

Step 2: Open a Menu Item

1. Click the arrow on the right of a menu item to expand it
2. Look for the Icon: row inside the expanded panel
3. Click Select

Step 3: Choose an Icon

1. The icon picker opens in a media modal titled Select Icon
2. Pick an icon type from the left side of the modal
3. Click the icon you want
4. The right sidebar shows a Preview and the per-icon settings

Step 4: Adjust and Save

1. Change Position, Font Size, Vertical Align or Hide Label in the modal sidebar if you want
2. Close the modal
3. Click Save Menu

Icons are written to the database only on a real Save Menu click on the Appearance > Menus screen. Adding an item over AJAX does not save the icon by itself.

To remove an icon, expand the menu item and click Remove next to the icon, then Save Menu. If either the type or the icon is missing, the theme deletes the stored value instead of saving a partial one.

Icon Types

Seven icon types are registered by default:

Type	What it gives you
Buddyx	Font Awesome classes, 604 icons in 18 groups
Dashicons	The WordPress admin icon font, 212 icons in 14 groups
Elusive	Elusive icon font, 290 icons in 6 groups
Foundation	Foundation icon font, 279 icons in 11 groups
Genericons	Genericons font, 147 icons in 8 groups
Image	An image you upload to the Media Library
SVG	An SVG file you upload to the Media Library

Registered but not enabled is not the same thing as available in the picker. Only the types you have enabled show up.

Setting	Where	Options
Icon Types	Sidebar of the Select Icon modal, under Icon Types Available	Any of the seven types above, plus any font packs you added

Default: buddyx only. The Buddyx type is the only one enabled out of the box.

To enable another type, open the icon picker on any menu item, tick the type in the Icon Types Available list in the modal sidebar, and click Load Icon Types. The page reloads with the type available.

The Buddyx type is Font Awesome. Every icon in it is a Font Awesome class string such as fa fa-chevron-square-up or fab fa-wpforms. It works on the front end because BuddyX Pro loads its own bundled assets/css/fontawesome.min.css on every page under the style handle buddyxpro-load-fontawesome.

Font Packs

No font pack ships with the theme, but the Fontello pack loader does. If you drop a font pack into wp-content/fontpacks/<pack-dir>/ with a config.json that carries name, glyphs and css_prefix_text, the pack is registered as its own icon type named Pack: (the name comes from config.json, not the directory) and appears in the Icon Types Available list. The directory can be moved with the icon_picker_fontpacks_dir_path and icon_picker_fontpacks_dir_url filters.

Settings

These settings live in the sidebar of the Select Icon modal and apply to the menu item you are editing.

Setting	Options	Default
Hide Label	No, Yes	Default: No
Position	Before, After	Default: Before
Vertical Align	Super, Top, Text Top, Middle, Baseline, Text Bottom, Bottom, Sub	Default: Middle
Font Size	Number in px, minimum 1, steps of 1	Default: 20
SVG Width	Number in em, minimum 0.5, steps of 0.1	Default: 1
Image Size	Any registered image size	Default: Thumbnail

What each one does:

• Hide Label set to Yes wraps the menu label in a visuallyhidden span. The text stays in the markup for screen readers, but sighted visitors see only the icon. Use this for icon-only rows in a compact header.
• Position puts the icon before or after the label text.
• Vertical Align sets the CSS vertical-align on the icon. Use it when the icon sits too high or too low against the label.
• Font Size sets the CSS font-size on the icon element in pixels. It applies to the font icon types (Buddyx, Dashicons, Elusive, Foundation, Genericons).
• SVG Width sets the CSS width in em on an SVG icon. It applies only to the SVG type.
• Image Size picks which registered attachment size is used for the Image type.

Values that match the default are not written into the inline style, so an icon left at 20px and Middle prints no style attribute at all.

BuddyPress Menu Items Get an Icon Automatically

When you add a BuddyPress item to a menu in Appearance > Menus, the theme fills in a Font Awesome icon for you before you touch anything. This happens only at the moment the item is added, and only for items that carry the bp-menu class.

BuddyPress item	Icon assigned
Profile	fa fa-user-alt
Settings	fa fa-users-cog
Activity	fa fa-chart-line
Notifications	fa fa-bell
Messages	fa fa-inbox
Friends	fa fa-users
Groups	fa fa-users
Forums	fab fa-wpforms
Documents	fa fa-file-alt
Photos	fa fa-image
MediaPress	fa fa-image
Invites	fa fa-envelope
Log Out	fa fa-sign-out-alt
Log In	fa fa-sign-in-alt
Register	fa fa-clipboard
Courses	fa fa-graduation-cap

The whole set of per-item values is seeded at the same time: type buddyx, Hide Label No, Position Before, Vertical Align Middle, Font Size 20, SVG Width 1, Image Size Thumbnail. You can change any of them before saving. You still have to click Save Menu for the icon to persist.

Side Menu Fallback Icon

Items in the side panel menu never render without an icon. If a menu item belongs to the menu assigned to Side Menu - Logged in users (buddyx-panel) and no icon is set on that item, the theme prints fa fa-link instead. For logged-out visitors the same rule applies to Side Menu - Logged out users (buddyx-panel-logged-out), falling back to the logged-in side menu if the logged-out location has no menu assigned.

Menu items in every other location print no icon when none is set.

The Menu Icons Plugin Is Blocked

The theme carries its own copy of this code, so the wordpress.org Menu Icons plugin (menu-icons/menu-icons.php) cannot run alongside it. Two guards enforce that.

Activation is intercepted. If you click Activate on the Menu Icons plugin row in Plugins, WordPress is redirected back to the plugins list before the plugin loads, and you see this error notice:

Menu Icons can’t be activated. The Buddyx Themes can’t work while Menu Icons plugin is active.

Anything that slips past is deactivated. If the plugin becomes active another way, for example bulk activation or WP-CLI, the theme deactivates it on the next request, front end or admin, and shows this notice the next time you load an admin screen:

Menu Icons is deactivate. Buddyx Themes can’t work while Menu Icons plugin is active. So Menu Icons is been deactivated

Both notices render on single-site and network admin. On any request where the plugin is still active, the theme’s own icon feature does not load at all, so the picker and front-end icons are absent until the deactivation has gone through.

Use Cases

A paid community running BuddyPress

You build a Side Menu containing Activity, Groups, Messages, Notifications and Settings. Each item picks up its Font Awesome icon the moment you add it, so the side panel reads as an app-style navigation rail without you choosing a single icon. Anything you add later that is not a BuddyPress item still gets the link fallback, so the rail never has a ragged row with a missing icon.

A course site

Your primary menu has Courses, My Account and Support. You set Hide Label to Yes on the cart or account item so the header stays short on tablet widths, and leave labels visible on the rest. The label text is still in the markup for screen readers and for search engines.

A vendor marketplace

The header holds Shop, Vendors, Become a Seller and Contact. You use the Image type for the Become a Seller item so it carries your own badge artwork rather than a font glyph, set Image Size to Thumbnail, and keep the other items on font icons at the default 20px so the row stays even.

A membership site with a long footer menu

You leave the footer menu without icons entirely and only add icons in the header and side panel. Because icons are per item, there is no global switch to fight: the footer items simply have no icon set, so nothing prints.

For Developers

Where the code lives

Path	Purpose
inc/compatibility/buddyx-menu-icons/menu-icons.php	Buddyx_Menu_Icons bootstrap, version 1.0.0, plugin block
inc/compatibility/buddyx-menu-icons/includes/settings.php	Menu_Icons_Settings, option handling, admin assets
inc/compatibility/buddyx-menu-icons/includes/picker.php	Menu_Icons_Picker, menu editor fields, save handler
inc/compatibility/buddyx-menu-icons/includes/meta.php	Menu_Icons_Meta, per item meta read and write
inc/compatibility/buddyx-menu-icons/includes/front.php	Menu_Icons_Front_End, icon markup on the front end
inc/compatibility/buddyx-menu-icons/vendor/kucrut/icon-picker/	The Icon Picker library and the shipped icon types
assets/css/fontawesome.min.css	The Font Awesome file behind the Buddyx icon type

The feature is required unconditionally from functions.php. The file itself is wrapped in a class_exists( 'Buddyx_Menu_Icons' ) guard, and everything past the bootstrap runs on init, then on icon_picker_init (fired from wp_loaded).

Storage

• Per item: post meta key menu-icons on the nav_menu_item post. Registered as protected via is_protected_meta, so it does not show in the Custom Fields box. Every submitted value passes through sanitize_text_field().
• Global: one option row named menu-icons.

Asset handles

Handle	Where
menu-icons (style)	css/admin.css, admin, nav-menus screen only
menu-icons (script)	js/admin.js, admin, depends on jquery and on icon-picker when any type is enabled
buddyxpro-load-fontawesome (style)	assets/css/fontawesome.min.css, front end, global

The admin script is localized as window.menuIcons with text, settingsFields, activeTypes, ajaxUrls.update and menuSettings.

Front-end markup

Icons are injected through the_title at priority 999. The filter is added on wp_nav_menu_args and removed on wp_nav_menu, so post titles outside menus are untouched. Classes: _mi on every icon, plus _before or _after when the label is visible, plus _image or _svg for those types. Hidden labels use the visuallyhidden class.

Actions

Action	Fired in	Arguments
menu_icons_loaded	After settings and front-end init	none
menu_icons_before_fields	Before the icon field in the menu item panel	$item, $depth, $args, $id
menu_icons_after_fields	After the icon field in the menu item panel	$item, $depth, $args, $id

The feature itself hooks icon_picker_init at priority 9 to collect registered types.

Filters

Filter	What it changes
menu_icons_types	The registered icon types array
menu_icons_settings_defaults	Default settings before the option is read
menu_icons_settings	The settings array after it is read
menu_icons_menu_settings	Per menu settings, receives $menu_id
menu_icons_disable_settings	Whether the sidebar settings meta box is skipped. Default: true in this fork
menu_icons_settings_sections	The settings sections array
menu_icons_settings_fields	The per item field definitions and their defaults
menu_icons_settings_js_data	Data localized to window.menuIcons
menu_icons_item_meta_values	Values just before they are written to meta
menu_icons_default_style	The default inline style rules (font_size 20px, vertical_align middle, svg_width 1em)
menu_icons_hidden_label_class	The hidden label class, visuallyhidden
menu_icons_item_title	The final title markup, receives $title_with_icon, $id, $meta, $title
icon_picker_type_props	Extra props passed to an icon type in JS
icon_picker_icon_type_stylesheet_uri	An icon type’s stylesheet URI
icon_picker_fontpacks_dir_path	Font pack directory path, defaults to WP_CONTENT_DIR . '/fontpacks'
icon_picker_fontpacks_dir_url	Font pack directory URL, defaults to WP_CONTENT_URL . '/fontpacks'

menu_icons_values still runs but is deprecated in favour of menu_icons_item_meta_values.

Text domain

Every string in the feature, including the vendored icon picker, uses the buddyxpro text domain.

Troubleshooting

The Icon Row Is Missing From Menu Items

Problem: No Icon: row appears when you expand a menu item.

Solutions:

1. Check Plugins for the Menu Icons plugin. If it is present, deactivate and delete it. While it is active the theme’s own feature does not load.
2. Look for the error notice at the top of the admin screen. Both block notices are described above.
3. Open Screen Options on Appearance > Menus and confirm Icon is ticked.
4. Check the browser console for JavaScript errors from another plugin on the menus screen.

The Icon Does Not Save

Problem: You pick an icon, but it is gone after a reload.

Solutions:

1. Click Save Menu after choosing the icon. Choosing alone does not write anything.
2. Confirm both a type and an icon are set. If either is missing, the stored value is deleted rather than saved.
3. Reload the menus screen and try again. The save runs only on the Appearance > Menus screen with a valid menu nonce, so a stale editor tab will not save.

The Icon Shows in the Admin but Not on the Front End

Solutions:

1. Confirm the menu is output by the theme through wp_nav_menu(). Menus placed by a page builder or a navigation block are not filtered.
2. Confirm the icon type is still enabled. If a type was turned off after icons were chosen with it, those icons stop rendering.
3. Clear any page cache and any CSS combining or optimization cache.

An Unwanted Link Icon Appears

Problem: Side panel items show a chain icon you did not choose.

Solution: That is the Side Menu fallback. Assign a real icon to the item to replace it.

A Menu Item Shows No Label

Problem: Only the icon is visible.

Solution: Expand the item, open the icon picker and set Hide Label back to No, then Save Menu. The label is present in the markup either way, it is only visually hidden.

Related Settings

• Navigation Menus - Menu locations and how to build a menu
• Header Elements - What sits in the header alongside the menu

---

Got a question? We’re a friendly team - happy to help.

• Visit our Documentation Portal
• Email us at support@wbcomdesigns.com