See the Issues page.

Frequently Asked Questions

What files do I need in order to run jqDock?

  • Just the script file – jquery.jqDock.js or jquery.jqDock.min.js (compressed version). Oh, and jQuery itself, of course!

I haven’t used jQuery before, so where do I get it and how do I use it?

  • You can get your own copy of the latest version of jQuery from http://jquery.com.
  • Alternatively, you can load jQuery from a CDN (Content Delivery Network) host, and http://docs.jquery.com/Downloading_jQuery has a list of CDNs for you to choose from.
    As an example, this could go in the headsection of your page…
    <script type='text/javascript' src='http://code.jquery.com/jquery-1.7.1.min.js'></script>
    <script type='text/javascript' src='http://code.jquery.com/jquery-1.7.1.min.js'></script>
  • As for using jQuery, well there is substantial documentation, including a number of tutorials, available on the jQuery site.
    But to simply get jqDock working, I would suggest looking at the source code of the examples on the Examples page, particularly the Images within links, labelled one (just don’t include my example.js file on any page you create, or clicking on your links will simply produce an alert!).
  • Using images within links (anchors) is probably the easiest way to implement jqDock because then you simply put the menu option’s target url into the link’s href attribute. This avoids having to get into things like click handlers if you’ve never used jQuery before.

Why isn’t the Dock being displayed?

  • Check that all necessary scripts are loading, ie. jQuery and jqDock. If your src paths are wrong then nothing’s going to work!
  • Check that jqDock() is being called after the document has loaded. (Ref. the jQuery tutorial : Launching Code on Document Ready).
  • Check that all your image paths are correct, because if jqDock fails to load any image the Dock will not be shown.
  • See if the Dock displays correctly in another browser – there is always the possibility that jqDock doesn’t work for your browser/operating system combination.
  • Try changing (or setting) the image loader (options.loader = ‘image’ or ‘jquery’). jqDock uses 2 types of image loader, and it could be that the default for your browser (ie. options.loader = 0) is incorrect.
  • Check for any elements other than images or link-wrapped images (IMG or A>IMG) in the menu that you are attempting to turn into a Dock.
  • As of v1.5, if you have set the onReady1.5 option up with a function that returns false then the display of the dock is down to you!

Why is nothing happening when I move my mouse over the images?

  • If you didn’t initially hide the Dock then you should first check through the responses above (under Why isn’t the Dock being displayed?).
  • Check that jqDock() is being called after the document has loaded. (Ref. the jQuery tutorial : Launching Code on Document Ready).
  • Check that some other element of your page is not obscuring the Dock, and thereby intercepting the events (this may seem unlikely but I can assure you that, having accidentally done it myself, it is very easy to do!).
  • As of v1.5, check that the Dock has not gone to sleep (see the Advanced page), either because you set the idle1.5 option, or because you instructed the Dock to go to sleep.
  • Check that the natural dimensions of your images are greater than the “at rest” size. jqDock does not “enlarge” images, it merely allows them to expand towards their natural size.

How do I make the menu vertical instead of horizontal?

  • Set the align option to be either ‘left’, ‘center’, or ‘right’ (see the align option on the Options page).

Why is the text of my links not being displayed?

  • jqDock removes all text nodes within the scope of the menu element, including link text. Not doing so would cause variations in the presentation of the Dock between browsers and DOCTYPE’d pages; it would also make the width/height calculations almost impossible.

Why am I not seeing labels on the Dock images?

  • The labels option is off by default.
  • Labels only appear on expanded images, and then only on the image currently beneath the cursor.
  • The text for a label is taken firstly from the title attribute of the menu image; if that is not available, and the image is wrapped in a link, then the title attribute of the link will be used. If neither of these are available, then no label will be displayed.
  • As of v1.5, you have the option to run a setLabel1.5 function on each label. If that function does not return a string (of HTML or text) then the label will have no content and will not be shown.

Can I change the position of the label?

  • As of v1.1, Yes (see Options, and Examples).
  • The positions can also be ‘tweaked’ by css styling of div.jqDockLabel, eg. adding padding to the label.
  • As of v1.5, text labels can be more comprehensively re-positioned by means of the additional inner wrapper, div.jqDockLabelText1.5. See the Examples.

How do I change the style of the labels?

How do I stop the image expansion being ‘jerky’?

  • There is actually very little you can do. Different browsers, different operating systems, and different machines, all make for a varied experience. I have reduced the processing overhead in the events handler as much as possible, and about the only thing you can try is turning off labels (if they are enabled), or placing them in a corner rather than using middle/center, and possibly reducing the distance option (the fewer images that are in an expansion state at any time, the less the processing involved). Sorry.

Why can’t I use an early version of jQuery?

  • jQuery evolves, and so does jqDock. The Usage and Change Log pages both state the minimum version of jQuery required for a particular version of jqDock, and the reason that it changes (infrequently!) is because jqDock may use new API features that get introduced with newer versions of jQuery. I have tried to maintain backward compatibility as much as possible, but there comes a time when it doesn’t make sense not to make full use of jQuery’s more recent capabilities.
  • If it doesn’t break any of your existing code, I would highly recommend upgrading to the most current version of jQuery, for speed and efficiency.

Why is the Dock disappearing under other element(s) on the page?

  • Because the target menu element (and its surrounding elements?) have not been correctly positioned in order to avoid just such a situation.
  • With the exception of converted lists (v2.0+), jqDock does not move or delete any elements from the page’s original HTML, and any inserted elements or wrappers are within the target menu element’s scope. The position of the Dock is totally dependent on the original styling applied to the target menu element, plus any additional styling you apply to div.jqDock.
  • As of v2.0, list conversion involves the insertion of a new DOM structure immediately before the original list. If the original list had an id then that id is transferred to the new structure, and css rules can be applied that distinguish between the list and jqDock structure, eg. ul#menu {} for the list, and div#menu {} for the Dock created from the list.

How do I change the appearance of the Dock?

Can I dynamically add/remove images (ie. menu options) on an existing Dock menu?

  • Yes, of course, with jQuery you can do almost anything you like … but you will corrupt the Dock’s layout and positioning, so I suggest that you don’t!
  • As of v1.6, you have the ability to ‘destroy’ the Dock (see Advanced). You can then manipulate the menu items as much as you like, and re-initialise the result.

Can I dynamically change images on an existing Dock?

  • Since v1.3, Yes. See the Alternate Options on the Options page. There are also a couple of examples of switching images – eg. Change source of images within links – on the Examples page.
  • Important! Only replace existing images with images of the same size, otherwise you will corrupt the Dock’s layout and positioning!

Can I disable elements of the Dock?

  • You can enable/disable clicks in the same manner that you would any other element.
  • jqDock does not control what happens when/if an element is clicked – you do. If your menu has any pure images (not wrapped in links) then you will have to bind any required click events to them. If there are linked images in the Dock then what happens when the link (the image) is clicked is down to you.
  • An example that visually ‘disables’ elements of the Dock is Change source of images within links on the Examples page.
  • Note that you can’t selectively hide/show elements of the Dock at will (except by making them invisible, which would leave gaps!). You also can’t selectively prevent elements from reacting to the mouse (in terms of expanding/shrinking).

Why do I need a large and a small image?

  • You don’t, you can just use the larger image. However, some images do not retain good clarity when reduced by a browser, so you therefore have the option of providing two purpose-built images: one for when the dock is not being expanded (‘at rest’), and one for when it is expanding.

Can I remove jqDock from a menu element?

  • As of v1.6, Yes, using the ‘destroy’ command (see Advanced). Prior to v1.6, No.

Can a Dock be given a ‘fixed’ position?

  • Yes. However, as with any other use of fixed position, you are going to have to be careful and meticulous with your HTML and CSS if you want it to work in all browsers. There is an example of a (very simple!) fixed position Dock (that even works for IE6, and IE7 in quirks mode) on the Examples page – Vertical, left-hand edge, fixed position.

Why does nothing happen when I click on a label?

  • Regardless of whether an image is contained within a link or not, clicking on its associated label will always trigger the ‘click’ event for the image.
  • Since v1.3, if the related image is contained within a link, then the label is also within that link, and should therefore activate the link in the same manner as clicking on the image itself.
  • [ Prior to v1.3, clicking on the label of an image within a link required that you provide a click handler for the label itself, which could trigger a handler on the relevant link. ]

Can I put more than one Dock on a page?

  • Yes. And you can supply each with its own unique (or not) set of options.

Can I upgrade from a previous version simply by swapping in a new version?

  • From v1.3 to v1.4, Yes.
  • From v1.5+ to anything up to v1.9, Yes.
  • From v1.5+ to v2.*, Yes, if your jQuery version already meets the new minimum requirements for v2.*, or you can easily upgrade it at the same time.
  • From v1.3/4 to v1.5+, Yes, if you initially hide your menu (as I do in all examples). As of v1.5, jqDock no longer hides the menu at the outset, so if you don’t already you might want to consider doing so? (The Change Log for v1.5 has possible ‘breaking changes’ indicated in red).
  • From a lower version (ie. pre v1.3), in principle, Yes, however you may need to be aware of the changes to some of the options defaults or minimum jQuery requirements (see the Change Logs)…
    • If you have styled (ie. positioned) a menu based on a previous default size of 36, the new default size of 481.3 may cause expanded menu items to encroach on other elements on your page (you may need to add size:36 to your options).
    • The other setting that might affect the presentation of your menu is a change to the default label position (from ‘tc’ to ‘tl’)1.3, if you have just set labels:true in your options.
  • Note : The Change Logs for any version will indicate (in red) any change that may break your current usage of jqDock, or possibly prevent you doing a simple version replacement.

Why are my image/anchor borders/margins disappearing?

  • Inline styling is applied to anchors and images that sets padding, margins, and borders to zero.
  • Why? Because it’s expensive (coding and processing) to measure and handle each of these, per image, on all four sides, and be consistent across browsers and Doc Types. Different browsers/Doc Types handle these attributes (margins, in particular) in different ways (and IE has caused me enough problems as it is!).

Why does the Dock take up so much room?

  • Because the images expand, and that extra space is needed for the images to expand into.
  • As of v1.5 there is a flow1.5 option which removes the Dock’s space reservation and auto-centering, but you should be very careful if you implement it; you (or your site’s visitors) may not like the result.

Can the jqDock automatically hide the Dock if it is not being used?

  • No. But as of v1.5, you can! (see the Advanced page)
  • There simply too many possibilities for jqDock to do anything itself : Hide it how? Slide or fade (or something else)? Slide it which way? Slide how far? Slide and fade? Fade over what period? Hide it when slid? Slide it under another element? Slide it off the viewport? Etc, etc, etc…
  • So … you now have the ability to do it for yourself. And there are even some Examples, such as Prepare on dockshow, with onSleep() slide up, to help you!
  • Please be aware that IE has certain problems with fading that jqDock handles for the Dock itself (div.jqDock and below), but if you fade the Dock wrapper or the original menu element you will have to cope with these issues yourself.

Can a menu element be designated as ‘active’, and be in an ‘expanded’ state when initialised?

  • As of v1.6, Yes. See active in the Options, and the Active item, click to toggle example on the Examples page.
  • Prior to v1.6, No.
  • A word of warning : Having a menu element expanded on initial display can be messy when the user first moves their cursor over the dock. The point at which they enter the dock could be some distance from the currently-expanded element, and it is therefore perfectly possible that the resultant animation will leave their cursor off the dock and the dock will collapse to ‘at rest’.

Can a designated ‘active’ element always be expanded when the mouse comes off the Dock?

  • With the functionality currently available in jqDock, No.
  • Let me see if I can explain why not.
    • (A) shows an ‘at-rest’ Dock, with the ‘eMail’ element designated as active
    • (B) shows the same Dock, with the cursor placed at the extreme right-hand limit of the ‘Terminal’ element
    • The dashed outline illustrates the difference between the ends of each Dock

    Let’s assume that an ‘at-rest’ Dock would always return to position (A) … and bear in mind that everything the Dock does is related to the cursor position within the Dock, and that as a result of what it does, the Dock’s width (horizontal menu) or height (vertical menu) changes.
    The problem occurs when the cursor moves into the dashed area :

    • According to (A), the ‘Terminal’ element is under the cursor and should expand
    • But, according to (B), the cursor is off the Dock so the Dock should be ‘at-rest’

    So, moving the cursor in (B)slightly to the right would result in :

    • jqDock reacts to the cursor coming off the Dock by going to ‘at-rest’
    • the ‘at-rest’ position – which is (A) – puts the cursor back on the Dock
    • jqDock attempts to expand ‘Terminal’, which is now under the cursor
    • as a result of expanding ‘Terminal’, the Dock shrinks and the cursor is now off the Dock (again)
    • …and repeat ad infinitum!

    Result : Vicious circle (ie. nasty ‘flicker’).

  • Is there a solution? Not while the Dock’s main axis dimension is variable.
  • Why isn’t this under Known Issues? Because it’s not an ‘issue’; it’s simply functionality that it is currently not possible to provide.
  • Is there an alternative? Of course. There are a number of other very good plugins that have functionality similar to jqDock’s.
  • Having said all the above, as of v1.6 it is possible for you to “sort of” simulate it, using the ‘active’ or ‘expand’ command strings (see Advanced), but you would have to do your own determination of when those commands should be called. You also need to consider the consequences of having an image already expanded when the cursor next enters the Dock (see the Word of Warning in the previous FAQ).

Can the menu elements be set up with sub-menus?

  • Yes, if you’re willing to take the trouble to set them up as labels.
  • The jqDock plugin is not aimed at multi-level navigation structures – it works for navigation by image, which is not naturally conducive to a multi-level type structure, hence the inability to work directly with lists.
  • However, it is possible to create the semblance of sub-menus by using the labels, particularly as of v1.6 (I would not recommend trying it with earlier versions). Should you wish to try it, I have put a Sub-menus as labels example on the Examples page.
  • The alternative is to set up a number of Docks – one per menu/submenu – and simply hide/show the relevant Dock depending on menu items clicked. This isn’t a multi-tiered menu, but rather a selective display of menu(s) according to a logical hierarchy that you impose. (See the Multiple menus for hierarchical option selection example on the Examples page)

How can my script determine whether a Dock is asleep or awake?

  • You can track it quite easily using the custom dockshow/sleep/wake events. And if you have supplied any onReady/onSleep/onWake hook functions then you know what they will return and when, so you can track those as well.
  • If you really get stuck, there is a command string – ‘get’ – that can be passed to jqDock() that will return a Dock’s internal object, within which the Asleepproperty indicates the current state of the Dock.
    var isSleeping = !!$('#menu').jqDock('get').Asleep; //true if 'asleep', false otherwise
    var isSleeping = !!$('#menu').jqDock('get').Asleep; //true if 'asleep', false otherwise

    The ‘get’ command will return either an object or null, and is therefore not chainable!.

  • As of v1.6 the Dock can also be ‘frozen’ (see Advanced), which can be checked by the state of the Frozen property. Note that a Dock that is Frozen is also (always!) Asleep, but the reverse does not necessarily apply.
  • The Demonstration Controller (on the jqDock Demonstrator page) tracks the Dock’s state (visually) without resorting to the ‘get’ command (the code – if you are interested, and if you can follow it! – is in this jqdock-docs.js file).

What is the difference between $().jqDock(‘nudge’) and $().trigger(‘docknudge’)?

  • Nothing really. They both end up running the same internal function, except that jqDock(‘nudge’) calls it directly (synchronously) while trigger(‘docknudge’) activates it via jQuery’s event handling mechanism.
  • The same applies for jqDock(‘idle’) vs. trigger(‘dockidle’), and for jqDock(‘freeze’) vs. trigger(‘dockfreeze’).

What is the difference between putting a dock to sleep and freezing it?

  • Freezing is only available from v1.6, and I have tried to explain it in the Sleep vs. Freeze section of the Advanced documentation.
  • In practical terms there is only one difference : freezing does not return the dock to its ‘at rest’ state; it literally ‘freezes’ the dock at whatever state of expansion it is at at the time.
  • In all other respects they do the same thing, with the end result that the dock is ‘asleep’. jqDock will let you know – via the hook functions and triggered events – whether the dock was ‘frozen’, or merely put to sleep.

Does jqDock work on lists (UL and OL tags)?

  • Prior to v2.0, No.
  • As of v2.0, Yes. Please check out the Lists documentation.

Why is the code for jqDock so large, and are there any alternatives?

  • Firstly, because I couldn’t get it any smaller without reducing the functionality, and making the source totally incomprehensible and the option names meaningless. I use Goggle’s Closure Compiler to compress the code; there are other utilities available, but the differences are negligible.
  • Secondly, Yes, of course there are. And they are undoubtedly smaller than jqDock, faster than jqDock, and simpler than jqDock. Are they better than jqDock? Probably. But that rather depends on whether they do what you want them to, doesn’t it.

How do I prevent the label text leaving a “trail”?

  • I have noticed that this can happen in Chrome (which is not to say it can’t happen in other browsers too!). In certain circumstances, an item’s label can leave a ‘trail’ of small dots behind when the mouse moves over the item. It’s not totally predictable, but seems to affect items at the end of the dock when the label is positioned at bottom-right.
  • The simplest way to avoid it (that I’ve found) is to just put a small padding – only needs to be 1px – in the label, eg…
    div.jqdockLabel {padding:0 1px;}
    div.jqdockLabel {padding:0 1px;}
 Posted by at 6:05 pm

  17 Responses to “FAQs”

Comments (17)
  1. hi, can i put a scroll if a have a lot options? thanks in advance!

  2. Is there a way to start out with the images not so small? I’d like them to start a bit closer to how big they end up.

  3. Hi, you say in the FAQ “As of v1.6, you have the ability to ‘destroy’ the Dock (see Advanced). You can then manipulate the menu items as much as you like, and re-initialise the result.”
    But when doing that it’s twinkle. Is there a way to add dynamically elements to the dock without twinkle?
    Like for a notification bar for example where elements popups inside?

    • Strictly speaking the answer is No, there is no way to dynamically add elements to a Dock.
      However, as the documentation implies, it is perfectly possible manipulate a non-Docked structure and then (re)initialise it. The “twinkle” that you refer to can be eliminated by careful and appropriate styling of the undocked structure. I have put together another example that does just this – Manipulate items in a dock – which might give you some pointers.

      The reason you can’t dynamically add/remove items from an initialised Dock is that jqDock does as much up-front (ie. during initialisation) processing as it can, so that calculations required while the Dock is “in action” (so to speak) are kept to a minimum and the animation of the Dock is as smooth as possible.

  4. Hello,
    Is there a possibility to make one of the topMenu a items a regular link like in the sub menus?
    I want to put my site logo on the topMenu and refer it to the site home page instead of to sub menu.
    Thanks, Yael

    • Sorry Yael, but you’ve lost me. Is there a particular example that you’re looking at? Because jqDock itself has no concept of top menus or sub menus – it’s essentially one-dimensional. You can use multiple docks to ‘simulate’ nested menus, but that’s about all.

      Sudden thought : maybe you are looking for help with the jqDock plugin for WordPress? If so, I’m sorry but you need to contact the plugin author, not me (I didn’t write it).

  5. Hi,
    I’m looking for a way to target the single most expanded image so I can toggle a class on it. I see jqDockExpand is added automatically, but it’s not unique to the primary expanded image. It stays on the neighboring images until they come to rest.

    I also looked at ‘isExpanded’ but it targets the dock as a whole and not the image element.


    • Hi Roger.
      Unfortunately there isn’t an easy way to do what you’re after. One problem is that there is not always going to be a “unique” primary expanded image because it is possible for 2 images to be expanded by the same amount (cursor mid way between them). In general I’m guessing that the “primary” image will be the one under the cursor (while the cursor is over the dock), so it should be possible to build a handler using mouseenter and jqdocks’s dockitem event, maybe something along the lines of…

      on mouseenter of any image (in the dock)
      - store the entered element
      - set the entered element’s class to xyz, having cleared xyz class from any other image
      on dockitem
      - if passed-in image == stored element AND passed-in boolean flag is FALSE
      - – then remove stored element’s xyz class

      This is off the top of my head and untested! But I think it should work in principle…

  6. Firstly I’d like to say thank you for a great piece of work, the documentation and examples are fantastic and I’ve enjoyed playing with the various scenarios.

    I do have a question of course, so here goes.
    I am not a web developer but do dabble and wanted to ask, how can you ensure that the menu appears on say an Apple Mac with JavaScript turned off?
    I know some Apples have Javascript disabled so is there a way they could still have a menu to work with?
    I am happy to scour the internet for example html etc but am hoping you can point me in the right direction?

    Kind Regards

    • Hi Gary.
      Well, from my point of view it’s quite simple : if a visitor’s browser has javascript turned off, then jqdock doesn’t run … end of story. It’s down to the builder of the web page to decide what gets presented in such a scenario. I guess that in most cases you’d just have the row (or column) of linked images.

  7. Hi, jqDock is very nice, I like it very much.

    BTW, can I use it to build one of our product which will be used commercially?


  8. How to set the size of JqDock. i try using this options. But not work.

    //the most commonly used options are likely to be align, size and labels,
    //closely followed by fadeIn and inactivity (other options are probably
    //for the more advanced user)
    var opts =
    // horizontal Dock with images expanding downwards in the vertical axis…
    { align: ‘top’
    // set the maximum minor axis (vertical) image dimension to 48px
    , size: 100


    Thank you

    • Hi
      In what way did it “not work”?
      Setting size to 100 (with align=top, as you have) restricts the “at rest” height of all the images to 100px. And widths are proportionate to the resultant height. If the images’ natural heights are greater than 100px than they will appear smaller when “at rest”, and subsequently “expand” when hovered over. If they aren’t, then they won’t change size (at all!).

  9. Hi, nice fluid menu. :)
    can we change the image expand to a smaller size?
    Can it be responsive?
    Can we put images size in % instead of pixels?
    Can it be touch enabled for mobile devices?

    Thank You in advance :)

 Leave a Reply



You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code lang=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre lang="" extra="">