Overview
Superfish is an enhanced Suckerfish-style menu jQuery plugin that takes an existing pure CSS drop-down menu (so it degrades gracefully without JavaScript) and adds the following much-sought-after enhancements:
- Suckerfish-style hover support for IE6. The class added is “sfHover” by default but can be changed via the options object,
- Timed delay on mouseout to be more forgiving of mouse-piloting errors. Default is 800 milliseconds but can be changed via the options object
- Animation of sub-menu reveal. uses a fade-in by default but can be given a custom object to be used in the first argument of the animate function. The animation speed is also customisable but is set to “normal” by default
- Keyboard accessibility. Tab through the links and the relevant sub-menus are revealed and hidden as needed
- Supports the hoverIntent plugin. Superfish automatically detects the presence of Brian Cherne’s hoverIntent plugin and uses its advanced hover behaviour for the mouseovers (mouseout delays are handled by Superfish regardless of the presence of hoverIntent). Using this is only an option, but a nice one. The examples on this page are using hoverIntent. If for some reason you want to use hoverIntent on your page for other plugins but do not want Superfish to use it you can set the option
disableHI
totrue
. - Indicates the presence of sub-menus by automatically adding arrow images to relevant anchors. Arrows are fully customisable via CSS. You can turn off auto-generation of the arrow mark-up via the “autoArrows” option if required.
- drop shadows for capable browsers – degrades gracefully for Internet Explorer 6. Can disable shadows completely via options object.
- Can show the path to your current page while the menu is idle. The easiest way to understand this is to view the nav-bar example.
- Optional callback functions. The 'this' keyword within the handlers you attach will refer to the animated ul sub-menu. From version 1.4 there are now three other optional callbacks allowing for further enhancements and functionality to be added without needing to alter the core Superfish code.
Quick Start Guide
- Begin with a working pure CSS dropdown menu just like you would if creating a Suckerfish menu - ie. for each li:hover selector, add an equivalent li.sfHover selector. To make this step easy, there are cross-browser CSS files for a variety of menu types available in the download section of this site.
-
Link to the superfish.js file using a script tag in the head of your document.
<script type="text/javascript" src="superfish.js"></script>
-
Call superfish() on the containing ul element.
There are many options available to customise your menu. You can find out about them in the Options tab of this site.<script> $(document).ready(function() { $('ul.sf-menu').superfish(); }); </script>
Options
Superfish’s default options:
$.fn.superfish.defaults = {
hoverClass: 'sfHover', // the class applied to hovered list items
pathClass: 'overideThisToUse', // the class you have applied to list items that lead to the current page
pathLevels: 1, // the number of levels of submenus that remain open or are restored using pathClass
delay: 800, // the delay in milliseconds that the mouse can remain outside a submenu without it closing
animation: {opacity:'show'}, // an object equivalent to first parameter of jQuery’s .animate() method
speed: 'normal', // speed of the animation. Equivalent to second parameter of jQuery’s .animate() method
autoArrows: true, // if true, arrow mark-up generated automatically = cleaner source code at expense of initialisation performance
dropShadows: true, // completely disable drop shadows by setting this to false
disableHI: false, // set to true to disable hoverIntent detection
onInit: function(){}, // callback function fires once Superfish is initialised – 'this' is the containing ul
onBeforeShow: function(){}, // callback function fires just before reveal animation begins – 'this' is the ul about to open
onShow: function(){}, // callback function fires once reveal animation completed – 'this' is the opened ul
onHide: function(){} // callback function fires after a sub-menu has closed – 'this' is the ul that just closed
};
You can override any of these options by passing an object into the Superfish method upon initialisation. For example:
//link to the CSS files for this menu type
<link rel="stylesheet" media="screen" href="superfish.css" />
// link to the JavaScript files (hoverIntent is optional)
<script src="hoverIntent.js"></script>
<script src="superfish.js"></script>
// initialise Superfish
<script>
$(document).ready(function() {
$('ul.sf-menu').superfish({
delay: 1000, // one second delay on mouseout
animation: {opacity:'show',height:'show'}, // fade-in and slide-down animation
speed: 'fast', // faster animation speed
autoArrows: false, // disable generation of arrow mark-up
dropShadows: false // disable drop shadows
});
});
</script>
Examples
The result:
The code:
The simplest use, and a good starting point for new users:
//link to the CSS files for this menu type
<link rel="stylesheet" media="screen" href="superfish.css" />
// link to the JavaScript files (hoverIntent is optional)
<script src="hoverIntent.js"></script>
<script src="superfish.js"></script>
// initialise Superfish
<script>
$(document).ready(function(){
$("ul.sf-menu").superfish();
});
</script>
The result:
Viewing this example in Internet Explorer will show that the sub-menus appear above the <select>
elements, as they should.
The code:
If your layout makes it likely that the sub-menus will be required to overlap <select>
form elements you will run into a bug in Internet Explorer 6 whereby the select elements appear above the sub-menus. You can fix this by applying Brandon Aaron’s bgIframe plugin like this:
//link to the CSS files for this menu type
<link rel="stylesheet" media="screen" href="superfish.css" />
// link to the JavaScript files (hoverIntent is optional)
<script src="hoverIntent.js"></script>
<script src="jquery.bgiframe.min.js"></script>
<script src="superfish.js"></script>
// initialise Superfish
<script>
$(document).ready(function(){
$("ul.sf-menu").superfish().find('ul').bgIframe({opacity:false});
});
</script>
The result:
The code:
To create an all-vertical menu, simply add the class sf-vertical
to the parent ul along with the usual sf-menu
class (space-separated, eg. class="sf-menu sf-vertical"), and initialise as normal. For this example I will also demonstrate altering some of the options in order to create a slide-down animation and a longer delay on mouseout:
//link to the CSS files for this menu type
<link rel="stylesheet" media="screen" href="superfish.css" />
<link rel="stylesheet" media="screen" href="superfish-vertical.css" />
// link to the JavaScript files (hoverIntent is optional)
<src="hoverIntent.js"></script>
<src="superfish.js"></script>
// initialise Superfish
<script>
$(document).ready(function(){
$("ul.sf-menu").superfish({
animation: {height:'show'}, // slide-down effect without fade-in
delay: 1200 // 1.2 second delay on mouseout
});
});
</script>
The result:
Notice that if you disable JavaScript this menu degrades very nicely – as do all the other examples.
The code:
To create a horizontal nav-bar with a horizontal second tier and optional vertical third tier, simply include the superfish-navbar.css file after the main superfish.css file and add the class sf-navbar
to the parent ul along with the usual sf-menu
class (space-separated, eg. class="sf-menu sf-navbar"), and initialise as normal.
A nice option to add to this types of menu is restoring the relevant sub-menu when the user is not exploring other sub-menus. This can be done by telling Superfish the name of the class you are adding to the relevant <li>
elements to indicate the path to the current page. I often have the server add the class name 'current' for this purpose, so I would initialise this menu thusly:
//link to the CSS files for this menu type
<link rel="stylesheet" media="screen" href="superfish.css" />
<link rel="stylesheet" media="screen" href="superfish-navbar.css" />
// link to the JavaScript files (hoverIntent is optional)
<script src="hoverIntent.js"></script>
<script src="superfish.js"></script>
// initialise Superfish
<script>
$(document).ready(function(){
$("ul.sf-menu").superfish({
pathClass: 'current'
});
});
</script>
The result:
The code:
This menu uses the optional Supersubs plugin (currently beta) to make the sub-menu widths variable. The fixed width set in the CSS is overridden and all menu items within a sub-menu are altered to match the width of their widest sibling. This is most commonly used to make all menu items fit on one line so that they are all of equal height.
Note that Supersubs needs to be called before Superfish in the initialisation chain, as shown below:
//link to the CSS files for this menu type
<link rel="stylesheet" media="screen" href="superfish.css" />
// link to the JavaScript files (hoverIntent is optional)
<script src="hoverIntent.js"></script>
<script src="superfish.js"></script>
<script src="supersubs.js"></script>
// initialise Superfish
<script>
$(document).ready(function(){
$("ul.sf-menu").supersubs({
minWidth: 12, // minimum width of sub-menus in em units
maxWidth: 27, // maximum width of sub-menus in em units
extraWidth: 1 // extra width can ensure lines don't sometimes turn over
// due to slight rounding differences and font-family
}).superfish(); // call supersubs first, then superfish, so that subs are
// not display:none when measuring. Call before initialising
// containing tabs for same reason.
});
</script>
Frequently Asked Questions
- Which versions of jQuery is the Superfish plugin compatible with?
- The Superfish plugin is compatible with jQuery v1.2 and later.
- Does the Superfish plugin have any dependencies on other plugins?
- Nope.
- Does the Superfish plugin work with any other plugins?
- Yes – here are a few useful plugins that you may wish to add to your menu:
- HoverIntent. The nicest thing you can do for your menu is include Brian Cherne’s hoverIntent plugin in your page and Superfish will automatically use it to make the user interaction more pleasing.
- $.event.special.hover. A new and improved special event implementation Brian Cherne’s "hoverIntent" plugin. $.event.special.hover simply overrides jQuery’s regular hover() function, so just link to this plugin and Superfish will use it automatically.
- Supersubs. If you want the submenu widths to change to suit their contents, you can add the Supersubs plugin as shown in the example of the same name on this site.
- BgIframe. Another plugin you may need is Brandon Aaron’s bgIframe plugin. This will solve the Internet Explorer bug described in the ‘bgIframe’ example on this site. 90% of people will not need this (yes I made up that statistic).
- How can I make the menu look better?
- The demo style is very basic by design – you should use it as a base to build upon and skin it to suit your project. I strongly recommend testing in Internet Explorer 6 in addition to modern browsers at every step of the way so that when IE6 bugs occur you can tell which CSS rules trigger them and work around them before moving on.
- What if something goes wrong?
- The cause of 99.9% of all Superfish problems are basic CSS issues. Disable JavaScript and concentrate on getting the menu working in pure CSS. If you are not a CSS expert then I advise that you follow the method described in the previous question’s answer, ie. begin with the demo CSS file and make small incremental changes, checking in a variety of browsers at every step.
- In Internet Explorer the submenus appear underneath main content div. Why? How do I solve it?
- This very common issue is thanks to the IE Z-index Bug and the solution does not involve adjusting any of the Superfish code, but rather, you need to apply certain CSS to some of your main site structure elements (usually the header div and the main content div). Please follow this link to an article that clearly explains the IE z-index bug fix for Superfish.
- What if I still need help?
- If you need help with the jQuery/JavaScript aspect of the plugin, post a message to the jQuery Forum with the word “Superfish” somewhere in the subject line. There are many Superfish users on the forum who may be able to help you.
- If your issues are related to styling and CSS, then you will need to post your questions to a purely CSS related group instead. CSS for Superfish is mainly just regular Suckerfish-style dropdown menu code so there are plenty of resources out there to learn from.
- Can I count on Superfish being supported into the future?
- Yes, it’s here for the long haul – or at least as long as it’s relevant. I will also be adding further features in the form of modular optional add-on plugins.
- Have you made any other plugins?
- Why yes, I’m thrilled that you asked. Check out my WordPress plugin “NoFollowr” for making judicious application of nofollow attributes a breeze. It is also powered by the mighty jQuery.
Download
A zip archive for Superfish is available here: Superfish-1.4.8.zip.
The zip archive contains the following files:
- example.html
- superfish.css
- superfish-vertical.css
- superfish-navbar.css
- jquery-1.2.6.min.js - but you should use the latest version of jQuery instead
- superfish.js
- supersubs.js
- arrows-ffffff.png – alpha transparent 8-bit png arrow image blends with your colour scheme – degrades to solid for IE6
- shadow.png – alpha transparent 32-bit png shadow image
- changelog.txt
Downloads for other plugins that can enhance a Superfish menu are available off-site:
- hoverIntent plugin by Brian Cherne
- bgIframe plugin by Brandon Aaron
Support
Support for the JavaScript component of the Superfish plugin is available through the jQuery Forum. Post a message to it with the word “Superfish” somewhere in the subject line. There are many other Superfish users on the list who may be able to help you. This is a very active mailing list to which many jQuery developers and users subscribe.
Most people’s issues relate to the actual CSS of the menu, which are best discussed elsewhere on a dedicated CSS forum.