Superfish Dropdown Menu
Integrates the jQuery Superfish plugin with Drupal menus to create beautiful, accessible dropdown navigation menus.
superfish
Install
composer require 'drupal/superfish:8.x-1.13'
Overview
The Superfish module integrates the popular jQuery Superfish plugin with Drupal's menu system, allowing site builders to create sophisticated dropdown navigation menus. It provides enhanced menu blocks that support horizontal, vertical, and navbar layouts with smooth animations, drop shadows, and arrow indicators.
The module includes extensive support for responsive design through the sf-Smallscreen and sf-Touchscreen plugins, which automatically adapt menus for mobile devices based on window width or user agent detection. Smallscreen mode can convert menus to either accordion-style navigation or dropdown select elements.
Superfish also supports multi-column mega menus, custom styling options (with pre-built themes for black, blue, coffee, white, and default styles), and various animation effects including vertical, horizontal, and diagonal slide-ins. The optional jQuery Easing library integration provides additional animation effects.
Key features include hoverIntent for preventing accidental menu activation, Supposition for intelligent sub-menu positioning within the viewport, and Supersubs for dynamic sub-menu width calculation. The module is fully accessible with ARIA attributes and supports RTL languages.
Features
- Multiple menu types: horizontal (single row), horizontal double row (navbar), and vertical (stack) layouts
- Pre-built visual styles: Default, Black, Blue, Coffee, White, or None for custom styling
- Slide-in animation effects with vertical, horizontal, and diagonal options
- Integration with jQuery Easing library for advanced animation effects (easeInSine, easeOutBounce, etc.)
- Responsive design with sf-Smallscreen plugin that converts menus to accordions or select elements on mobile
- sf-Touchscreen plugin for touch device compatibility with configurable tap behaviors
- Supersubs plugin for automatic sub-menu width calculation based on content
- Supposition plugin for intelligent sub-menu positioning to prevent overflow outside viewport
- jQuery hoverIntent integration to prevent accidental menu firing during quick mouse movements
- Multi-column mega menu support with configurable depth and levels
- Custom CSS classes for UL, LI, and hyperlink elements
- Link description insertion or hiding (title attribute handling)
- Depth-based CSS classes (sf-depth-1, sf-depth-2, etc.) for advanced styling
- Clone parent links option to add parent link at top of sub-menus for easier navigation
- Path level restoration using active-trail classes
- Support for menu expanded option to show only expanded parent sub-menus
- Configurable animation speed (slow, normal, fast, or milliseconds)
- Configurable mouse delay for sub-menu closing
- RTL language support with automatic direction detection
- ARIA attributes for accessibility (role=menu, aria-haspopup, aria-expanded)
- User agent detection methods: client-side (JavaScript) or server-side (PHP)
- Window width breakpoint configuration for responsive features
- Integration with translatable_menu_link_uri module for multilingual link overrides
- Integration with menu_manipulator module for language-based menu filtering
Use Cases
Main Site Navigation with Dropdown Menus
Create a horizontal navigation bar with multi-level dropdown sub-menus. Place a Superfish block in your header region, select the Main navigation menu, use horizontal menu type with the default style, enable arrows and shadows for visual polish, and enable hoverIntent to prevent accidental sub-menu activation.
Responsive Mobile-First Navigation
Build navigation that adapts to mobile devices. Configure the Superfish block with sf-Smallscreen enabled using window width mode with a 768px breakpoint. Choose accordion type for the mobile menu, which provides a touch-friendly expandable navigation. Also enable sf-Touchscreen for tablet devices to ensure first-tap expands and second-tap navigates.
Mega Menu with Multi-Column Layout
Create a mega menu for e-commerce or content-heavy sites. Enable multi-column sub-menus in block settings, set the starting depth to 1, and configure 2-3 levels. This creates wide sub-menus with multiple columns, ideal for displaying category hierarchies. Use custom CSS classes to further style the columns.
Vertical Sidebar Navigation
Add a vertical navigation menu to a sidebar region. Select vertical menu type, which stacks menu items vertically with sub-menus appearing to the side. Enable Supposition to ensure sub-menus stay within the viewport boundary. This is ideal for admin interfaces or secondary navigation.
Touch-Optimized Navigation
Configure menus specifically for touchscreen devices. Enable sf-Touchscreen with user agent detection, select the behavior where first tap shows children and second tap opens the link. Enable clone_parent option to add parent links at the top of sub-menus, making it easier for touch users to navigate to parent pages.
Custom Themed Navigation
Create a navigation with completely custom styling. Set the Style option to 'None', then copy one of the sample stylesheets from the library to your theme. Rename or remove the .sf-style-default selectors and apply your own CSS. Add custom classes using the Advanced settings to target specific elements.
Tips
- Use a DOM inspector like Firefox Developer Tools to temporarily modify menu styles in real-time while developing custom themes
- Set the Mouse delay to a very high value (e.g., 99999999) during development so sub-menus stay open longer for inspection
- When customizing styles, copy the sample CSS from the library's style directory to your theme rather than modifying the library files directly
- The module automatically generates unique HTML IDs for menu items using the pattern {menu_name}-{link_id}
- Enable hoverIntent to improve user experience by preventing menus from activating during quick mouse movements across the navigation
- The Supposition plugin is enabled by default and intelligently repositions sub-menus that would otherwise appear outside the browser window
- For sites with many menu levels, use the Path levels setting carefully - changing it from the default of 1 may cause unexpected behavior with active trail highlighting
- Multi-column menus work best with consistent content across columns; test with real content to ensure balanced layouts
- When using user agent detection for responsive features, server-side PHP detection provides faster initial rendering but client-side JavaScript is more accurate for proxy users
- The module integrates automatically with the translatable_menu_link_uri and menu_manipulator modules when they are installed
Technical Details
Hooks 1
hook_superfish_tree_manipulators_alter
Allows modules to alter the list of menu tree manipulators used when building Superfish menus. Manipulators can modify menu items, filter access, sort items, or transform links before rendering.
Troubleshooting 8
Clear the Drupal cache at Administration > Configuration > Development > Performance. If the library is not installed, you will also see a warning message.
Verify the Superfish library is installed in libraries/drupal-superfish/ directory. Check the Status report (Administration > Reports > Status report) for library status. Ensure the library contains superfish.js and the css folder.
Enable the jQuery Supposition plugin in block settings, which repositions sub-menus to stay within the browser window. Also check z-index values in your theme CSS if menus appear behind other elements.
Enable sf-Touchscreen and/or sf-Smallscreen in block settings. For touch devices, configure the breakpoint value (default 768px) and test on actual devices. Ensure your theme includes the viewport meta tag: <meta name="viewport" content="width=device-width, initial-scale=1.0">
Install the jQuery Easing library by downloading jquery.easing.js and placing it in libraries/easing/jquery.easing.js. After installation, refresh the block configuration page to see additional easing animation options.
Check that menu links are configured with correct paths. The module uses both route matching and URL comparison to determine active states. For anchor links (#), only the base path is compared.
When using Style: None with sf-Smallscreen accordion mode, you must either set a custom Accordion menu title or apply custom CSS to style the accordion toggle button. The default styles provide visibility, but None style requires custom implementation.
Adjust the Animation speed setting (default: fast) and Mouse delay setting (default: 800ms). Lower values make menus more responsive. Consider disabling hoverIntent if immediate response is needed, though this may cause accidental activation.