Skip to Content

Docs navigation

for Documentation

Quick setup

Include the script and CSS files on your page:

<!-- jQuery -->
<script src="jquery-1.4.4.min.js" type="text/javascript"></script>
<!-- SmartMenus jQuery plugin -->
<script src="jquery.smartmenus.js" type="text/javascript"></script>

<!-- SmartMenus core CSS (required) -->
<link href='sm-core-css.css' rel='stylesheet' type='text/css' />
<!-- "sm-blue" menu theme (optional, you can use your own CSS, too) -->
<link href='sm-blue/sm-blue.css' rel='stylesheet' type='text/css' />

The menu definition is a standard unordered list structure:

<ul id="main-menu" class="sm sm-blue">
  <li><a href="#">Item 1</a></li>
  <li><a href="#">Item 2</a>
    <ul>
      <li><a href="#">Item 2-1</a></li>
      <li><a href="#">Item 2-2</a></li>
      <li><a href="#">Item 2-3</a></li>
    </ul>
  </li>
  <li><a href="#">Item 3</a></li>
</ul>

You always need to set the sm class and, optionally, if you would like to use some of the default themes, set it's class too (e.g. like sm-blue in the example above).

If you would like to have a vertical main menu instead of horizontal, you also need to set the sm-vertical class (and sm-blue-vertical if you use the "sm-blue" theme):

<ul id="main-menu" class="sm sm-vertical sm-blue sm-blue-vertical"> ...

The script is initialized like any other jQuery plugin:

$(function() {
  $('#main-menu').smartmenus();
});

Options

bottomToTopSubMenus
Type: Boolean
Determines whether the sub menus should be displayed from bottom to top (drop-up) instead of top to bottom (drop-down).
collapsibleHideDuration
Type: Integer
The duration for hide animation for collapsible sub menus. This option matters only if collapsibleHideFunction: null
collapsibleHideFunction
Type: null, Function
Custom function to use when hiding a collapsible sub menu (the default is the jQuery 'hide').
Code sample:
collapsibleHideFunction: function($ul, complete) { $ul.SlideUp(250, complete); }
Note: Don't forget to call complete() at the end of whatever you do with the $ul (the sub menu).
collapsibleShowDuration
Type: Integer
The duration for show animation for collapsible sub menus. This option matters only if collapsibleShowFunction: null
collapsibleShowFunction
Type: null, Function
Custom function to use when showing a collapsible sub menu (the default is the jQuery 'show').
Code sample:
collapsibleShowFunction: function($ul, complete) { $ul.SlideDown(250, complete); }
Note: Don't forget to call complete() at the end of whatever you do with the $ul (the sub menu).
hideDuration
Type: Integer
The duration in milliseconds for hide animation. Set it to 0 for no animation. This option matters only if hideFunction: null
hideFunction
Type: null, Function
Custom function to use when hiding a sub menu (the default is the jQuery 'hide').
Code sample:
hideFunction: function($ul, complete) { $ul.fadeOut(250, complete); }
Note: Don't forget to call complete() at the end of whatever you do with the $ul (the sub menu).
hideOnClick
Type: Boolean
Determines whether to hide (reset) the sub menus on click/tap anywhere on the page.
hideTimeout
Type: Integer
The timeout in milliseconds before hiding (resetting) the sub menus on mouseout/focusout.
isPopup
Type: Boolean
Determines whether the menu is a popup menu or a permanent menu bar. Popup menus can be shown/hidden via the popupShow and popupHide API methods. Make sure you position offscreen or hide with display:none in your CSS any popup menus you have.
keepHighlighted
Type: Boolean
Determines whether all ancestor items of the current sub menu should be kept highlighted - the script adds the highlighted class to the links (the A elements).
keepInViewport
Type: Boolean
Determines whether the sub menus should be repositioned if needed to make sure they always appear inside the viewport.
Type: Integer
Allows setting a horizontal offset in pixels from the default position for the first-level sub menus. You may want to check the subMenusSubOffsetX option, too.
Type: Integer
Allows setting a vertical offset in pixels from the default position for the first-level sub menus. You may want to check the subMenusSubOffsetY option, too.
markCurrentItem
Type: Boolean
Determines whether the script should automatically add the current class to the A element of the item linking to the current page URL.
markCurrentTree
Type: Boolean
Determines whether the script should automatically add the current class to the A elements of all ancestor items of the current item. This option matters only if markCurrentItem: true
overlapControlsInIE
Type: Boolean
Determines whether the script should make sure the sub menus appear on top of special OS controls in Internet Explorer (i.e. SELECT, OBJECT, EMBED, etc.) You may opt to disable this feature if you don't need this fix and would like to achieve best possible runtime performance in IE (other browsers are not affected anyway).
rightToLeftSubMenus
Type: Boolean
Determines whether the sub menus should be displayed from right to left instead of left to right. You may need to check and update the CSS for the sub indicators' position, too (i.e. look for span.sub-arrow).
scrollAccelerate
Type: Boolean
Determines whether to accelerate scrolling or use a fixed step for long sub menus that do not fully fit in the viewport height (i.e. start slower and then gradually increase the step).
scrollInterval
Type: Integer
Interval in milliseconds between each scrolling step for long sub menus that do not fully fit in the viewport height.
scrollStep
Type: Integer
Step in pixels when scrolling long sub menus that do not fit in the viewport height.
showDuration
Type: Integer
The duration in milliseconds for show animation. Set it to 0 for no animation. This option matters only if showFunction: null
showFunction
Type: null, Function
Custom function to use when showing a sub menu (the default is the jQuery 'show').
Code sample:
showFunction: function($ul, complete) { $ul.fadeIn(250, complete); }
Note: Don't forget to call complete() at the end of whatever you do with the $ul (the sub menu).
showOnClick
Type: Boolean
Determines whether to show the first-level sub menus onclick instead of onmouseover - i.e. like drop-down menus on desktop applications. This option matters only for mouse input.
showTimeout
Type: Integer
The timeout in milliseconds before showing the sub menus on mouseover/focusin.
subIndicators
Type: Boolean
Determines whether to create sub menu indicators. The script creates a SPAN and inserts it in the item's A element.
subIndicatorsPos
Type: String
Position of the sub menu indicator SPAN relative to the menu item content. A keyword specifying the jQuery method to use when inserting the SPAN in the menu item's A element - either 'prepend', or 'append'.
subIndicatorsText
Type: String
A text string to be added in the sub menu indicator SPAN (e.g. '+'). You may need to check and update the CSS for the sub indicators, too (i.e. look for span.sub-arrow).
Type: String
Max-width for the sub menus in any valid CSS unit. If a value is set, any fixed width set in CSS will be ignored by the script.
Type: String
Min-width for the sub menus in any valid CSS unit. If a value is set, any fixed width set in CSS will be ignored by the script.
Type: Integer
Allows setting a horizontal offset in pixels from the default position for the second+ level sub menus. You may want to check the mainMenuSubOffsetX option, too.
Type: Integer
Allows setting a vertical offset in pixels from the default position for the second+ level sub menus. You may want to check the mainMenuSubOffsetY option, too.

Events

activate
Fired when an item is activated, right before its sub menu (if the item has a sub menu) is shown. You can cancel the event with return false and the item's sub menu will not be shown.
Cancelable: Yes
Arguments:
e
The jQuery.Event object.
item
The menu item A element.
Code sample:
$('#main-menu').bind('activate.smapi', function(e, item) {});
beforefirstshow
Fired only once for each sub menu, right before it's shown for the first time. You could use it, for example, for some initialization tasks that need to be called just once. You can cancel the event with return false and the sub menu will not be shown.
Cancelable: Yes
Arguments:
e
The jQuery.Event object.
menu
The sub menu UL element.
Code sample:
$('#main-menu').bind('beforefirstshow.smapi', function(e, menu) {});
beforehide
Fired right before a sub menu is hidden. You can cancel the event with return false and the sub menu will not be hidden.
Cancelable: Yes
Arguments:
e
The jQuery.Event object.
menu
The sub menu UL element.
Code sample:
$('#main-menu').bind('beforehide.smapi', function(e, menu) {});
beforeshow
Fired right before a sub menu is shown. You can cancel the event with return false and the sub menu will not be shown.
Cancelable: Yes
Arguments:
e
The jQuery.Event object.
menu
The sub menu UL element.
Code sample:
$('#main-menu').bind('beforeshow.smapi', function(e, menu) {});
blur
Fired when an item loses focus.
Cancelable: No
Arguments:
e
The jQuery.Event object.
item
The menu item A element.
Code sample:
$('#main-menu').bind('blur.smapi', function(e, item) {});
click
Fired when an item is clicked. You can cancel the event with return false and the item will not be selected (i.e. it's link won't be loaded) and if there is a sub menu which should appear on click, it won't be shown, too. This event is fired even for disabled items so you may want to check the select event, too.
Cancelable: Yes
Arguments:
e
The jQuery.Event object.
item
The menu item A element.
Code sample:
$('#main-menu').bind('click.smapi', function(e, item) {});
focus
Fired when an item is focused.
Cancelable: No
Arguments:
e
The jQuery.Event object.
item
The menu item A element.
Code sample:
$('#main-menu').bind('focus.smapi', function(e, item) {});
hide
Fired right after a sub menu is hidden.
Cancelable: No
Arguments:
e
The jQuery.Event object.
menu
The sub menu UL element.
Code sample:
$('#main-menu').bind('hide.smapi', function(e, menu) {});
mouseenter
Fired when an item is hovered.
Cancelable: No
Arguments:
e
The jQuery.Event object.
item
The menu item A element.
Code sample:
$('#main-menu').bind('mouseenter.smapi', function(e, item) {});
mouseleave
Fired when an item is hovered out.
Cancelable: No
Arguments:
e
The jQuery.Event object.
item
The menu item A element.
Code sample:
$('#main-menu').bind('mouseleave.smapi', function(e, item) {});
select
Fired when an item is selected, right before it's link is loaded. You can cancel the event with return false and the item will not be selected (i.e. it's link won't be loaded). This event is not fired for disabled items so you may want to check the click event, too.
Cancelable: Yes
Arguments:
e
The jQuery.Event object.
item
The menu item A element.
Code sample:
$('#main-menu').bind('select.smapi', function(e, item) {});
show
Fired right after a sub menu is shown.
Cancelable: No
Arguments:
e
The jQuery.Event object.
menu
The sub menu UL element.
Code sample:
$('#main-menu').bind('show.smapi', function(e, menu) {});

Methods

Global methods

The following methods are global for all menu instances.

destroy
Destroys all menu instances initialized on the page and cleans up everything.
Code sample:
$.SmartMenus.destroy();
hideAll
Hides (resets) all sub menus of all menu instances on the page.
Code sample:
$.SmartMenus.hideAll();

Instance methods

The following methods are available for each menu instance.

blur
Use the native JavaScript method for any menu item's A element if you need. This will deactivate the item and hide any sub menus.
Code sample:
$('a#myItem')[0].blur();
destroy
Destroys the menu instance and cleans up.
Code sample:
$('#main-menu').smartmenus('destroy');
disable
Disables the menu and optionally displays a transparent overlay DIV over the main menu.
Arguments:
noOverlay
Type: Boolean
Default value: false
If true is passed, no overlay will be displayed over the main menu.
Code sample:
// disable the menu
$('#main-menu').smartmenus('disable');

// disable the menu but don't display an overlay over the main menu
$('#main-menu').smartmenus('disable', true);
enable
Enable the menu after it has been disabled.
Code sample:
$('#main-menu').smartmenus('enable');
focus
Use the native JavaScript method for any menu item's A element to send keyboard focus to it. Note that you may need to call itemActivate first to make sure the menu containing the item is visible when you try to focus it, otherwise the item might not be focused by the browser.
Code sample:
$('a#myItem')[0].focus();
itemActivate
Activates any menu item. This will show its sub menu (if the item has a sub menu). If you want to also send keyboard focus to the item, you can additionally call the focus method.
Arguments:
$a
Type: jQuery
The jQuery wrapped A element of the item you would like to activate.
Code sample:
// activate the item
$('#main-menu').smartmenus('itemActivate', $('a#myItem'));

// activate the item and focus it
$('#main-menu').smartmenus('itemActivate', $('a#myItem'));
$('a#myItem')[0].focus();
Hides (resets) all sub menus.
Code sample:
$('#main-menu').smartmenus('menuHideAll');
popupHide
Hides any popup menu. A menu is a popup menu when the isPopup: true option is set. When isPopup: false the main menu is permanent (always visible) and cannot be hidden with this method.
Arguments:
noHideTimeout
Type: Boolean
Default value: false
If true is passed, the menu will be hidden immediately, otherwise the hideTimeout option specifies the delay before hiding the popup menu.
Code sample:
// hide a popup menu
$('#popup-menu').smartmenus('popupHide');

// hide a popup menu immediately without a delay
$('#popup-menu').smartmenus('popupHide', true);
popupShow
Shows any popup menu. A menu is a popup menu when the isPopup: true option is set. When isPopup: false the main menu is permanent (always visible) and cannot be shown with this method.
Arguments:
left
Type: String
Pass a value for the CSS left declaration to be set for the popup menu before it is shown.
top
Type: String
Pass a value for the CSS top declaration to be set for the popup menu before it is shown.
Code sample:
// show the popup at left:100px;top:100px;
$('#popup-menu').smartmenus('popupShow', '100px', '100px');

// show the popup right below some target element
var $targetElm = $('#targetElm'),
    targetOffset = $targetElm.offset();
$('#popup-menu').smartmenus('popupShow', targetOffset.left, targetOffset.top + $targetElm.outerHeight());
refresh
Refreshes (re-initializes) the menu after any DOM operations have been applied - e.g. adding/removing items and sub menus or completely replacing the innerHTML of the root UL element.
Code sample:
var $menu = $('#main-menu');

// append a new main menu item
$menu.append('<li><a href="#">New item</a></li>');

// add a sub menu with 3 items to the new main menu item
$menu.children('li:last').append('<ul>\
  <li><a href="#">New item</a></li>\
  <li><a href="#">New item</a></li>\
  <li><a href="#">New item</a></li>\
</ul>');

// refresh the menu after the DOM operations
$menu.smartmenus('refresh');

Tutorials

Styling the menus

You can style the menus and items the same way you can style any other unordered list on your page. The UL elements represent the menu boxes and the A elements - the menu items.

You always need to include on your pages the SmartMenus core CSS sm-core-css.css which includes just some basic rules that take care of things like resetting default list styles, main menu items arrangement, etc. And then you can either use (and modify to suit your needs) some of the default themes, or you can even use your own CSS to style the menus and items as you like.

There are some classes that you can and may need to set to your main menu (the root UL element):

sm
This is a required class you always need to set to any menu you are going to use.
Code sample:
<ul id="main-menu" class="sm"> ...
sm-vertical
Setting this class will make your main menu vertical and the items will appear one below the other. By default when this class is not set, the main menu is horizontal.
Code sample:
<ul id="main-menu" class="sm sm-vertical"> ...
sm-rtl
You need to set this class if the text in the menus is right-to-left - e.g. Hebrew, Arabic, etc. Read Using the script with RTL text (e.g. Hebrew, Arabic) for more info.

If you use some of the default menu themes, you will also need to set its class too - e.g. sm-blue and possibly sm-blue-vertical for the default blue theme.

There are some classes that you can set or are set automatically by the script to the menu items (the A elements):

disabled
You can set this class to any menu item to make it disabled. User clicks on disabled items are neglected by the script.
Code sample:
<li><a href="#" class="disabled"> ...
current
You can configure the script to set this class automatically to the item linking to the current page URL that is loaded by the browser (and optionally to its parent items). This would allow you to style the current item differently from all other items. You can control this feature via the markCurrentItem and markCurrentTree options.
highlighted
When the keepHighlighted: true option is set, the script will automatically add this class at runtime to any item that has its sub menu displayed. The class is removed as soon as the sub menu is hidden.
has-submenu
The script sets this class on init to all items that have sub menus.

Supporting touch devices

Both touch and mouse input are supported by default. You don't need to do anything about it - your menus will just work and respond to whatever input is available on the device. The script even supports simultaneous touch and mouse input (for example, an Android device with a USB mouse plugged in, a Windows 8 touch-enabled device, etc.) which means that the menus will respond properly to the mouse cursor movement and any touches at the same time.

Supporting small-screen devices (responsive menus)

By default the script supports small-screen devices by transforming any horizontal or vertical main menu with drop-down sub menus into a vertical menu bar with collapsible sub menus when the browser viewport is not wide enough.

You can control in which cases (e.g. at what width) this should happen (and should it happen at all) by using CSS media queries like you do normally for your responsive page layouts. The default themes are all optimized for small screen devices and any menus that use these themes will be automatically transformed to collapsible menus at given viewport widths. For example, the default blue theme includes the following CSS:

@media screen and (max-width: 640px) {

  /* The following will make the sub menus collapsible for small screen devices (it's not recommended editing these) */
  ul.sm-blue{width:auto !important;}
  ul.sm-blue ul{display:none;position:static !important;top:auto !important;left:auto !important;margin-left:0 !important;margin-top:0 !important;width:auto !important;min-width:0 !important;max-width:none !important;}
  ul.sm-blue>li{float:none;}
  ul.sm-blue>li>a,ul.sm-blue ul.sm-nowrap>li>a{white-space:normal;}
  ul.sm-blue iframe{display:none;}

  /* more rules to style the collapsible menu bar ... */

}

These rules are basically what is required. When you use these, the script will automatically detect when the main menu should become collapsible and take care of everything. What you may want to edit in the above media query is the max-width: 640px part where you specify the exact width break point.

If you are not using any of the default themes (i.e. you are styling your menus from scratch) and would like to make your menus collapsible on narrow viewports, you will just need to use the above CSS - just replace ul.sm-blue with the class you use or even with an id selector for your root UL element:

Using the script with RTL text (e.g. Hebrew, Arabic)

To use the script with right-to-left text you just need to set the sm-rtl class to the root UL element:

<ul id="main-menu" class="sm sm-rtl"> ...
<!-- or -->
<ul id="main-menu" class="sm sm-vertical sm-rtl"> ...

and the script will take care of everything.

Here is some sample code that adds a menu toggle show/hide button on small screens.

HTML:

Add the collapsed class to the root UL element:

<ul id="main-menu" class="sm collapsed"> ...
<!-- or -->
<ul id="main-menu" class="sm sm-vertical collapsed"> ...
Add the menu button code on your page:
<a id="menu-button"></a>

CSS:

#menu-button {
  display:none;
  /* style it as you like... */
}
#menu-button:before {
  content:'Menu -';
}
#menu-button.collapsed:before {
  content:'Menu +';
}
@media screen and (max-width: 640px) {
  /* show the button on small screens */
  #menu-button {
    display:inline-block;
  }
  /* hide the menu when it has the "collapsed" class set by the script */
  #main-menu.collapsed {
    display:none;
  }
}

JavaScript:

$(function() {
  $('#menu-button').click(function() {
    var $this = $(this),
        $menu = $('#main-menu');
    if (!$this.hasClass('collapsed')) {
      $menu.addClass('collapsed');
      $this.addClass('collapsed');
    } else {
      $menu.removeClass('collapsed');
      $this.removeClass('collapsed');
    }
    return false;
  }).click();
});

This will show a menu toggle button (link) when the viewport width is less than 640px. This is, of course, just a basic example - you can tweak the styling of the button as you like, change the exact width breakpoint, etc.

Requirements

The script requires and fully supports jQuery 1.4.4+.