In usability we trust

UX and all things web

Announcing MapTooltip

One of the shortcomings in the Google Maps API is that there’s no easy way to add tooltips to polylines and polygons. That’s why I felt inclined to build an extension to Google Maps that adds that functionality. MapTooltip makes it possible to add tooltips to any kind of overlay. It’s even possible to have HTML inside it and to style it to fit your design needs.

About MapTooltip

In a project I’m working on there’s a need to have tooltips on polylines. I have tried to find simple ways of doing this but haven’t been able to find any. After researching this and eventually coming up with a solution I decided to package it into a small library so that I could share it with fellow Google Maps developers.


The constructor creates an object of the type MapTooltip. It takes two required arguments and one optional.

MapTooltip(reference:object, tooltip:string, opts?:object)


The first argument, reference, is a reference to the overlay that you will attach the tooltip to, for example a GPolyline.


The second argument, tooltip, is a string containing what will appear inside of the tooltip. You can either provide just a plain text string or some HTML.


The third argument which is optional, opts, is an object literal that contains all options on how the tooltip will look and behave. It can have the following settings:

  • width
    The width of the tooltip, ex: “100px”
  • padding
    The padding around the content of the tooltip
    For a 3px padding: “3px”
    For a 2px top/bottom padding and a 5px left/right padding: “2px 5px”
  • backgroundColor
    Backgroundcolor of the tooltip, ex: “#ff9”
  • color
    The color of the text inside the tooltip, ex: “#000”
  • border
    The styling of the border of the tooltip, ex: “1px solid green”
  • fontSize
    The size of the text inside the tooltip, ex: “1em”
  • offsetX
    The horizontal distance in pixels from the pointer to the tooltip, ex “10”
  • offsetY
    The vertical distance in pixels from the pointer to the tooltip, ex: “10”

It might for example look like this:

var options = {
'width': '250px',
'border': '3px dotted #00f'

Using MapTooltip

To use MapTooltip is pretty easy. First add a Google Map as you normally would. Then follow the steps below to attach a tooltip to an object in the map.

1. Load the library

Import the library to the web page with the script tag.

<script src="" type="text/javascript"></script>

2. Attach appropriate events

Add a mouseover event to the object on your map that you wish to have a tooltip. You will also have to add a mouseout event that removes the tooltip.

// Attach mouseover event to a polyline that will trigger the tooltip
GEvent.addListener(polyline, 'mouseover', function() {
	this.overlay = new MapTooltip(this, 'This is a polyline');
	// Attach mousout event to the polyline that will delete the tooltip
	GEvent.addListener(polyline, 'mouseout', function() {

That’s it. Be sure to check out the live demo to see it in action. The demo includes tooltips attached to markers, polylines and polygons. One of the tooltip is styled in a different way using the opts parameter.


MapTooltip is released under the MIT License and is free for any use.




MapTooltip is heavily influenced by the article Custom Info Window / Popup for Google Maps, or Loving the GOverlay.

Known bugs

If you import the Google Maps API with ver=2.x it’s not going to work as expected since it seems that it doesn’t handle mouseover events on GMap2 when the pointer is over an GOverlay quite the same way as in previous versions. I don’t know if this is a temporary glitch or if it’s supposed to work this way in the future.

Update [2009-04-11]: In the latest release of the Google Maps API the above mentioned problems currently occur. I will try to find a way around, but until then you can stick to version 2.151 to make it work correctly.

For ideas on this or for other bugs you might encounter, please contact me either in the comments or through the Contact page.


  1. This is great! If you’re interested in adding it to the utility library, send me an email.

  2. Great! I was looking for something like that for quite a while.

  3. Something strange is happening in the demo. The marker works as expected, but the polyline and polygon don’t show the tooltip until the cursor leaves the item of interest.

  4. Dave: The problem you’re experiencing is due to that Google is changing the API. I thought that running version 2.151 I would be safe, and yesterday when I checked it worked, but today it doesn’t. I tested again right now and now it seems safe to run version 2.149 or below of the API. I have updated the example accordingly.

    Naturally I need to find a way around this issue so it’s possible to run the latest version of the API, but so far I haven’t come up with a solution.

    Thanks for noticing!

  5. hi,
    congratulations for this library !
    its work fine when i use “tabloPolyline= new GPolyline(pts,colour,width);”
    but i have this warning when i try to use it with an array of polyline (ie 8, ff):
    “tabloPolyline[a] = new GPolyline(pts,colour,width);”

    Message : ‘__e_’ a la valeur Null ou n’est pas un objet.
    Ligne : 313
    Caractère : 28
    Code : 0
    URI :


  6. Nice job bro… but unfortunately i cannot use it in v3…..the tooltips displays unconsitently… with large number of polygons.. some time even more than one tooltips shows when the number of polygon is high……hope you will try in more than 10 polygons and fix the bug as soon as possible….

  7. LOVE THIS, but can’t get it to work!!!!

    I really want to use this code and cannot figure out how to implement it into my code…I took over some javascript duties and am still pretty new. I tried to paste my code into this window and it’s a total mess!! If you’re not too busy, maybe I could send you my code and you could give me a pointer on how to use your code with mine. I would be so thankful!!!!

  8. OKAY, GOOD DAY!!!

    Got it to work and looks great! I just had to move my code around a little


  9. Angie I’m glad that you got it to work and that you like it! Good luck with the coding!

  10. hi !
    do you have some news about mouseover problem with recent v2 api ?


  11. Any progress on getting your tooltips working beyond version 2.149? Many useful new features have been added to maps api. Up to version 2.172 and 3.11…
    Thanks though!

  12. 4. April 21st, 2009 at 7.29 you wrote:

    “Naturally I need to find a way around this issue so it’s possible to run the latest version
    of the API, but so far I haven’t come up with a solution.”

    It’s actually not your script – it a appears to be bug in the latest API.

    I already had this exact same problem when simply trying to use the following single line in the mouseover event: = “pointer”;

    I tried version 3 and the problem is still there.
    So it looks for now, like we’re stuck with 2.149.

  13. Even with 50 polygons it still works like a charm – as long as we stick to v2.149

  14. Tyler: I’m glad to hear that you find it useful.

    I suggest that we file a bug report to the Google Maps API. It would be sweet if they could fix that so that it works in newer versions of the API.

  15. Hi,
    I am glad to find this tooltip.
    But I have the same problem as No.5.
    It works for simple polygon. but I count not work out with polygon array.
    I am looking forword to hearing any advice.
    Thank you.

  16. Thanks a lot. This is a great tool. I am able to use it. I have one issue when using it with an map that does have the dragging capability (map.disableDragging()). This tooltip code somehow overrides it. Do you have any idea how to disable the pan icon to prevent the dragging from happening. Thanks

  17. Hey! Tnx a lot for this script! 😉

    Found one more bug. When I zoom in map, tooltip wont dissappear after I move mouse out of polygon. It shows some kind of “Uncaught TypeError: Cannot call method ‘removeChild’ of null. MapTooltip.remove” in mapTooltip.js 108 row. + it drops some errors from main.js, so it seems like it’s kind of problem with API too.

    my test map (will be there for a while):
    map js:

  18. Seems to work fairly well. You may want to remove the memory leak moving the mouseout event binding outside the mouseover function. Right now it keeps adding mouseout events.


    April 1, 2011 at 4:27 pm

    Oh , really great , that’s what i am looking for.
    But i have a question , can we modify this class so that it has rounded corners and it can be crossed the map boundries , just like the yelp style google map info window.

  20. Your solution works really fine for Google Maps API version 2.x. Do you have an solution or code snipplet for version 3.x?

Leave a Reply

Your email address will not be published.