Menu Item Role Access
Provides role-based access control for menu items, allowing administrators to restrict menu item visibility based on user roles.
menu_item_role_access
Install
composer require 'drupal/menu_item_role_access:8.x-2.4'
composer require 'drupal/menu_item_role_access:8.x-2.1'
Overview
Menu Item Role Access is a Drupal module that adds fine-grained role-based access control to menu items. By default, Drupal's menu system shows or hides menu items based on whether the user has access to the link's target page. This module extends that functionality by adding a role selection field directly to menu items, enabling administrators to control which user roles can see specific menu items regardless of the underlying page access.
The module adds two fields to menu link content entities: a multi-value role reference field that specifies which roles can view the menu item, and a boolean field that allows parent menu items to override access settings for all their children. This hierarchical inheritance feature is particularly useful for managing complex menu structures where entire branches should be restricted to certain user groups.
The module provides configuration options to override Drupal's default internal link target access checking behavior, allowing menu items to be shown to users who have the appropriate role assignment even if they don't have direct access to the target page. This is especially useful for external links, special routes like
Features
- Role-based visibility control for individual menu items allowing selection of multiple user roles
- Parent-to-children access inheritance with 'Override children' option that propagates role restrictions down the menu hierarchy
- Configurable behavior to override Drupal's internal link target access check, enabling menu items to display based solely on role assignment
- Support for special route types including <nolink>, <none>, and <front> page links
- Automatic caching with user.roles cache context for proper cache invalidation
- Field-level access control ensuring only users with proper permission can edit role assignments
- Full integration with Drupal's menu_link_content entity system through base field definitions
Use Cases
Member-only navigation section
Create a menu section visible only to authenticated members. Add menu items to a Members menu and select only the 'authenticated' role in the Menu Item Roles field. Anonymous visitors will not see these menu items even if they can access the target pages.
Role-specific dashboard links
Show different dashboard links to different user roles. Create separate menu items for 'Editor Dashboard', 'Manager Dashboard', and 'Admin Dashboard', each restricted to their respective roles. All items can exist in the same menu but will only appear for users with matching roles.
Hierarchical department menus
Create a department-specific menu structure where an entire branch is restricted. Set up a parent 'Finance Department' menu item restricted to the 'finance_staff' role with 'Override children' enabled. All child items (Reports, Budgets, Invoices) will automatically inherit the restriction without needing individual configuration.
External link visibility control
Control visibility of external links based on roles. Add external links (e.g., to partner portals or premium resources) and restrict them to specific subscription tiers or membership levels using role assignment.
Non-link menu headers for specific audiences
Create section headers using <nolink> routes that are only visible to certain roles. For example, a 'Premium Features' header that only appears for premium subscribers, with its children also restricted appropriately.
Anonymous-only menu items
Display certain menu items only to anonymous (non-logged-in) users, such as 'Register' or 'Login' links. Assign only the 'anonymous' role to these items so they automatically disappear once a user logs in.
Tips
- Always clear caches after changing module configuration settings for changes to take effect
- Use the 'Override children' feature to simplify management of large menu hierarchies - set restrictions on parent items rather than configuring each child individually
- For external links or special routes (<nolink>, <none>, <front>), enable 'Overwrite internal link target access check' to ensure role-based restrictions work properly
- When no roles are selected on a menu item, it remains visible to all users (default Drupal behavior)
- The module adds cache contexts for user.roles, ensuring proper cache handling for role-based visibility
- Test menu visibility by logging in as different user roles or using a role-switching module to verify access settings work as expected
Technical Details
Admin Pages 1
/admin/config/menu-item-role-access
This configuration page allows administrators to control the global behavior of the Menu Item Role Access module. It provides options to modify how the module interacts with Drupal's default access checking system and whether child menu items should inherit access restrictions from their parents.
Permissions 2
Hooks 4
hook_entity_base_field_info
Adds two base fields to the menu_link_content entity type: 'menu_item_roles' (entity reference to user_role with unlimited cardinality) and 'menu_item_override_children' (boolean field for inheritance control).
hook_form_menu_link_content_form_alter
Alters the menu link content form to conditionally hide the 'menu_item_override_children' field based on whether the 'inherit_parent_access' configuration option is enabled.
hook_entity_field_access
Controls access to the 'menu_item_roles' field, ensuring only users with 'edit menu_item_role_access' permission can edit the field. View access is forbidden to prevent information disclosure, while edit access requires the specific permission.
hook_help
Provides help text for the module's help page explaining that the module adds an optional role field to menu items for access control.
Troubleshooting 5
By default, Drupal's core permissions at /admin/people/permissions take precedence. If a role has view permissions for the target content, they may see the menu item regardless of Menu Item Role Access settings. Navigate to /admin/config/menu-item-role-access and enable 'Overwrite internal link target access check', then clear the cache.
The user's role may lack Drupal core permissions to view the target content. Either grant the necessary core permissions or enable 'Overwrite internal link target access check' at /admin/config/menu-item-role-access to bypass the target access check.
Ensure 'Allow parents to override children' is enabled at /admin/config/menu-item-role-access. Also verify the parent menu item has the 'Override children' checkbox enabled in its edit form. For best results, also enable 'Overwrite internal link target access check'.
The current user needs the 'Edit The Menu Item Role Access Field' permission. Grant this permission at /admin/people/permissions to the appropriate roles.
Clear all caches using drush cr or through /admin/config/development/performance. The module uses cache contexts that may require a full cache rebuild to take effect.
Security Notes 4
- This module controls menu item visibility only - it does not provide access control to the actual pages. Users may still access restricted pages directly via URL if they have the necessary page-level permissions
- The 'Overwrite internal link target access check' option should be used carefully as it can make menu items visible for pages users cannot actually access, potentially revealing site structure
- Role assignments on menu items are stored as entity references and require the 'edit menu_item_role_access' permission to modify, preventing unauthorized changes to visibility settings
- The module respects Drupal's 'link to any page' permission - users with this permission bypass all menu item role checks