Responsive and off-canvas menu
Provides a responsive menu system with off-canvas mobile navigation using the mmenu library and an optional horizontal menu for desktop widths.
responsive_menu
Install
composer require 'drupal/responsive_menu:^4.4'
Overview
The Responsive Menu module integrates the mmenu JavaScript library with Drupal's menu system to provide a modern, responsive navigation experience. At narrower browser widths, it displays an off-canvas mobile menu that can be triggered by a toggle icon (hamburger menu) or swipe gesture. At wider screen widths, it can display a horizontal menu with optional dropdown support via the Superfish library.
The module integrates with your theme's breakpoints to allow precise control over when the horizontal menu appears. It supports multiple visual themes (light, dark, black, white), left/right/contextual positioning for RTL languages, page dimming effects when the menu opens, and Bootstrap 4 theme compatibility.
Two blocks are provided: a horizontal menu block for desktop navigation and a mobile toggle icon block for opening the off-canvas menu. The horizontal menu block is optional - you can use only the off-canvas menu or integrate with other menu solutions like Bootstrap's navbar.
Features
- Off-canvas mobile menu powered by the mmenu JavaScript library with smooth slide-out animations
- Horizontal desktop menu with configurable maximum depth and optional Superfish dropdown enhancements
- Integration with theme breakpoints to control when horizontal menu displays vs. mobile menu
- Four built-in visual themes: Light, Dark, Black, and White
- Configurable menu position: left, right, or contextual (auto-switches based on language direction for RTL support)
- Page dimming effects when menu opens: none, default color, white, or black
- Optional swipe/drag gesture to open mobile menu
- Bootstrap 4 theme compatibility mode - hijacks Bootstrap navbar toggler to open mmenu
- Superfish library integration for enhanced dropdown behavior with configurable delay, speed, and hoverIntent support
- Ability to merge multiple Drupal menus into a single off-canvas menu structure
- Fly-left option for third-level and deeper menu items to prevent off-screen flyouts
- IE11 polyfills support
- Automatic page wrapper div insertion for themes that lack one
- Chrome viewport fix for proper mobile rendering
- Keyboard navigation support in off-canvas menu
- Extensive alter hooks for customizing menu behavior
Use Cases
Mobile-first responsive navigation
Use the module to provide a consistent mobile-first navigation experience. Place the 'Responsive menu mobile icon' block in your header region. At mobile widths, users see the hamburger icon which opens a full-featured off-canvas menu. Configure a breakpoint (e.g., 960px) at which the toggle icon hides and optionally display a horizontal menu block for desktop users.
Off-canvas only navigation
If you prefer to use only the off-canvas menu at all screen sizes, uncheck 'Use a breakpoint' in settings. This keeps the mobile toggle icon visible at all widths. This approach works well for sites with complex navigation that benefits from the off-canvas presentation regardless of screen size.
Merging multiple menus for mobile
Many sites have separate main navigation and utility menus (account, language selector, etc.) at desktop widths. Use the 'off_canvas_menus' setting to specify multiple menu machine names (e.g., 'main,utility') to merge them into a single off-canvas menu for mobile users, providing a unified mobile navigation experience.
Bootstrap 4 theme integration
For sites using Bootstrap 4 themes like bootstrap_barrio, enable 'Bootstrap compatibility mode'. Place your Main navigation block in the 'Navigation (Collapsible)' region. The module will automatically hijack Bootstrap's navbar toggler button to open the mmenu off-canvas menu instead of Bootstrap's default dropdown, providing a more polished mobile experience.
RTL language support
For multilingual sites supporting RTL languages like Arabic or Hebrew, set the off-canvas position to 'Contextual'. The menu will automatically open from the left for LTR languages and from the right for RTL languages, following expected reading patterns.
Enhanced dropdown menus with Superfish
Enable Superfish integration for the horizontal menu to get enhanced dropdown behavior including configurable delays, smooth animations, and optional hoverIntent support for more forgiving hover interactions. This is particularly useful for menus with multiple levels of dropdowns.
Touch-friendly mobile navigation
Enable the 'drag to open gesture' option to allow mobile users to swipe from the edge of the screen to open the off-canvas menu, in addition to tapping the toggle icon. This provides a more native mobile app-like experience.
Custom menu per page via hooks
Use hook_responsive_menu_off_canvas_menu_names_alter() or hook_responsive_menu_horizontal_menu_name_alter() to display different menus on different pages. For example, show a special landing page menu on the front page or a section-specific menu within certain content areas.
Tips
- Copy the module's CSS (css/responsive_menu.css) into your theme and disable 'Load the responsive_menu module's css' for easier customization.
- Use hook_preprocess_page() in your theme to add custom mmenu configuration via drupalSettings.responsive_menu.custom for advanced options like navbar titles or custom class names.
- The default 'menu-item--active-trail' class for selected items works with themes using classy as base. Override via custom config if your theme uses different classes.
- The mmenu library has changed to a Creative Commons Attribution-NonCommercial license - you'll need to pay for commercial use. Check https://mmenujs.com for licensing details.
- For best performance, the off-canvas menu is rendered once and cached. Clear the 'offcanvas_render' cache tag when making changes that should immediately reflect.
- Test menu functionality across different browsers and devices, especially if supporting older browsers - enable IE11 polyfills if needed.
- When using merged menus, items appear in the order menus are listed. Put your primary navigation menu first for expected ordering.
Technical Details
Admin Pages 1
/admin/config/user-interface/responsive-menu
Configure all aspects of the responsive menu including which menus to display, breakpoint settings, visual appearance, and JavaScript enhancements.
Hooks 7
hook_responsive_menu_off_canvas_menu_names_alter
Alter the menu names used by the off-canvas responsive menu. Allows changing which menu(s) are displayed in the off-canvas mobile menu based on conditions.
hook_responsive_menu_horizontal_menu_name_alter
Alter the menu name used by the horizontal responsive menu. Allows displaying different horizontal menus on different pages.
hook_responsive_menu_off_canvas_tree_alter
Alter the off-canvas menu tree after it has been built. Allows modifying menu item titles, attributes, or structure.
hook_responsive_menu_horizontal_tree_alter
Alter the horizontal menu tree after it has been built. Allows modifying menu item titles, attributes, or structure.
hook_responsive_menu_off_canvas_manipulators_alter
Alter the manipulators before transforming the off-canvas menu tree. Allows adding custom menu tree manipulators.
hook_responsive_menu_horizontal_manipulators_alter
Alter the manipulators before transforming the horizontal menu tree. Allows adding custom menu tree manipulators.
hook_responsive_menu_off_canvas_output_alter
Alter whether the off-canvas menu should be shown. Useful for disabling the menu under specific conditions such as for certain themes, user roles, or pages.
Troubleshooting 8
Ensure the mmenu library is properly installed at /libraries/mmenu/dist/mmenu.js. Check the status report at /admin/reports/status for library requirements. Also verify your theme has a wrapping page div - if not, enable 'Add a page wrapper div to the front end theme' in settings.
Verify the 'Horizontal menu' block is placed in a region. Check that 'Use a breakpoint' is enabled and a valid breakpoint is selected. Ensure your theme has breakpoints defined in its .breakpoints.yml file. Clear caches after changing breakpoint settings.
Enable the 'Dynamically modify the viewport meta tag' option. Chrome requires specific viewport values for mmenu to render correctly on mobile devices.
Ensure 'Bootstrap compatibility mode' is enabled. Verify the Bootstrap navbar toggler is within an element with ID #navbar-main. Check that your main navigation block is in the correct region.
Verify the Superfish library is installed at /libraries/superfish/dist/js/superfish.min.js. Note that Superfish requires jQuery, so your theme must include jQuery. Check the status report for library requirements.
The module includes toolbar integration code that handles this. If issues persist, ensure the responsive_menu.toolbar library is being loaded. Try clearing all caches.
Edit the parent menu item and check the 'Fly left' option (available for items at depth 3 or greater). This causes child items to fly out to the left instead of right, preventing off-screen rendering.
The breakpoint CSS is generated in public://css directory. Ensure this directory is writable. Clear caches to trigger regeneration. Check that your theme has valid breakpoints defined.
Security Notes 2
- The module respects Drupal's menu access controls - only menu items accessible to the current user are displayed.
- The mmenu library uses a NonCommercial Creative Commons license. Ensure compliance with licensing terms for commercial projects.