Imagemap Tutorial


"Imagemapping" is a procedure for associating different parts of an image with links to different URLs. The first type to be defined and implemented was the "server-side imagemap"; the type that's mostly used nowadays is known as a "client-side imagemap". Several different designs of client-side imagemap have been proposed: the one in common use today was originally proposed by Spyglass and first published in RFC1980. Other imagemapping techniques are mentioned at the end, but not covered in this tutorial.

A recent detailed documentation can be found in the HTML4 specification, see Client-side image maps in the W3C HTML4.01 spec. "Client-side imagemaps" of this type are, for most purposes, a better design than the original server-side imagemaps, and are supported (with some limitations) by current browser versions; the older browser versions which did not support them are little-used today, but it's up to you whether you want to still support them - it does no harm to add server-side support if you can do so for relatively little effort. First we describe the two kinds separately, then we show how they can be combined, to produce an element that works as a client-side map on those browsers which support it, and falls back to a server-side map on those which don't.

Although this and other tutorials show you how things work, for practical application, I recommend you to use an imagemapping utility. Many web authoring packages include one, or lists of available mapping tools can be found in the FAQs or at W3C, Yahoo etc. I offer no comparative critique of the various products: the one that I've been using, for MS Windows PCs, is a now-unsupported free package called "Map_THIS!". It supports both client-side and server-side mapping formats, but the author has dropped it in favour of a payware implementation which, although offering more user features, apparently only supports client-side mapping. Copies of Map_THIS! can still be found in repositories of free software or by looking for mpths131.exe with a search engine. Note that the field which is described as "Internal comment" on the "Edit Area Info" dialogue is the one that will be used as an ALT attribute for AREA tags in the client-side map, so I recommend you to fill in this field appropriately.

(Don't be misled by some authoring packages which create pages reliant on non-HTML techniques, such as Javascript actions in the client-side code and proprietary procedures on the server side. These aim to lock you into that vendor's particular product line and discourage you from subsequently migrating to competing products. Be sure to choose a package which supports the standard techniques that are capable of being ported between different kinds of web server; and which are able to work on any client agent, rather than making pages needlessly dependent on techniques - such as client-side scripting - which a proportion of users may decide to disable for their own good reasons. There's nothing wrong with using Javascript etc. to offer optional extras that cannot be provided in other ways, but, where the same functionality can be provided using standard HTML techniques available to "any" user, it's pointless to make the function dependent on Javascript.)

On the whole, the help file that comes with Map_THIS! is also quite a good tutorial on image-mapping, though I have a few quibbles. There's no explicit mention of the ALT attribute for the AREA tag. The Map_THIS! documentation confusingly refers to the Client-side imagemap as "HTML3.0", but in fact the only kind of imagemap that was mentioned in the expired 1995 HTML3.0 draft was the FIG (now obsolete).

The purpose of this tutorial is not to replace the use of an appropriate software tool, but to give you insight into what happens "under the covers" and help you to produce a page that will work in the widest possible range of browsing situations. To quite an extent, this page duplicates tutorials at IHiP. But there were some features that I specially wanted to bring out. In particular, IHiP fail to make any mention of the ALT attribute of the AREA tag, and they no longer describe how to make dual client-side/server-side maps (their demonstration map is one, but they don't say so!). Also, they omit to deal with the issue of overlapping areas, which I found out from usenet and email discussion is a source of confusion for quite a number of users.

Server-side Maps

With the server-side map, most of the machinery is in the server. The browser needs to do nothing more than to attach the pixel co-ordinates of a click to a URL and send it to the server. All the rest of the work is done at the server.

The ingredients of the server-side imagemap solution are:

Since the actual evaluation of the co-ordinates is done entirely within the server, there does not have to be an interworking standard for the imagemap data file and its evaluator program, and, originally, each server developer defined their own format of map data file. Fortunately, not too many different formats have come into general use: basically there is the "CERN" format, and the "NCSA" format ("Apache" supports the NCSA format with some extensions). Some evaluators have been designed to support more than one format.

You will need to find out what the arrangements are on the particular server that you use in order to be sure that you are generating the correct format of imagemap, and using the correct URL for invoking it. This tutorial can only cover a few typical ways in which this might be done.

You should be aware that there are differences in the ways that pixel co-ordinates are used in the different map formats, for example a circle in one format is defined by its center and radius, while in another format it is defined by its center and by one of the points on its circumference.

Although, not surprisingly, the imagemap file will be on the same server as the imagemap evaluator, that doesn't necessarily have to be the same server that the actual HTML document and the image came from. Indeed, there's nothing stopping you from writing an HTML document that you put on one server, that retrieves an image from a second server, and invokes the imagemap evaluator program on a third server where you have placed your imagemap. Nevertheless, for simplicity we'll assume that all these things are on the same server, unless otherwise stated, since that is the most usual state of affairs in practice.

The image, and your HTML, and the map file, are all made available on your server in the usual way. The following HTML fragment is appropriate for all server-side maps, and some examples are given in what follows.

<A HREF="URL-for-mapping"><IMG SRC="URL-to-image" ISMAP></A>

The IMG tag needs an appropriate ALT attribute, and normally also HEIGHT and WIDTH, in the usual way. The TITLE and LONGDESC are also available for promoting accessibility, in accordance with the principles of the WAI.

In circumstances where the page already has adequate navigation facilities for a text-mode user, you could "hide" the imagemap from text-mode browsers by specifying ALT="", but this is certainly not the only possible approach: an alternative and often preferable method would be to arrange things so that if the text-mode reader uses the map, the server will send a text-mode menu. There's a more detailed discussion of this topic on my text-friendly imagemaps page.

There follows a presentation of some typical server situations and usages. On a first reading of this tutorial, you might prefer to skip to Client-side maps, and come back to this detail later.

NCSA server, using "Internal Imagemap" support

This replaces the earlier, and clumsier, "imagemap program" method, description of which has been omitted for brevity. Both methods were fully covered in NCSA's tutorial. Although the NCSA server itself is no longer supported, Apache's behaviour is based on similar principles, so this is still useful background.

The format of the map file entries is

method target-URL coord1 coord2 ... coordn

where each coordn consists of pixel x and y co-ordinates separated by a comma. For example

rect 15,8 135,39

The imagemaps need to be given a "magic content-type" of text/x-imagemap, which triggers the server to handle them specially. Any method could be used to assign the magic content-type, but for the sake of a definite example, let us suppose that the magic content-type is associated in the server with a filename extension of .map

Then, in the HTML, the URL-for-mapping takes the form of simply the local part of the URL of the imagemap itself, for example href="/newbie/mydir/"

When the imagemap is actually used, the browser will attach the x and y pixel co-ordinates of the click to the URL-for-mapping, and send the resulting request to the server. The server will respond by following the normal procedure for invoking a CGI program (in this case, the imagemap evaluator program), passing it the virtual path that defines the imagemap data file, and the query-string that defines the x and y co-ordinates of the click. The result from the imagemap evaluator will be a target document URL, or it may be a do-nothing default. There are two kinds of target URL supported by the NCSA server:

A local URL (virtual path), such as /newbie/mypage.html
The server returns the contents of the specified page immediately

A fully specified URL, such as
The server returns a relocation to the indicated URL.

Note that the two scenarios have different consequences for caching. It can be beneficial (except where the documents are very small) to cause relocation to take place by using the second form, even when the target is a local one. You must use the second form for the target, in any case, if the target document is access-controlled: the NCSA server will refuse to serve-out an access-controlled document if you use the first kind of target.

Another situation where the second form of URL is essential, is when you wish to use the #fragment notation in the target URL.

"Default" action

Server-side imagemaps may (or may not, depending on the server support) require a "default" URL to be defined, to be used when a spot is clicked-on that lies within the imagemap but does not correspond to one of the active areas that have been listed in the map. There are various ways of using this feature:

Advice! Think about this from the point of view of the user. They clicked on the image map because they expected something (useful) to happen. So, I'd say your first priority as an author, if you can possibly do something useful for them, would be to make it happen. Doing nothing, or presenting them with a nastygram, really isn't very friendly, and should surely only be resorted to if there is a genuine risk of something harmful happening when you misunderstand their wishes. So, unless your imagemap is designed to do something irreversible (which wouldn't usually be a good idea anyway), it would mostly seem advisable to offer them something - possibly a text menu - they can always use their Back function if it wasn't what they wanted.

Apache server

Apache supports server-side imagemaps by means of a "module" called mod_imap: this is more efficient than a conventional CGI program such as the NCSA imagemap program. As far as the URL-for-mapping is concerned, it looks like the URLs used with "NCSA server with Internal Imagemap support" just described. Server configuration (although this would normally be a matter for your server admin) is via the "AddHandler" directive: for compatibility with NCSA, the "magic content-type" can be used in an AddType directive instead.

The handler supports several formats of image map file, of which the NCSA imagemap format is a special case. Thus, the Apache handler can deal with existing NCSA imagemaps; however, for optimal functionality (if it is known that the map is going to be used on an Apache server, or one that supports this format), the following is recommended:

method target-URL coord1 coord2 ... "Menu text"

where each coordn consists of pixel x and y co-ordinates separated by a comma. For example:

rect 15,8 135,39 "W3 Consortium"

Note the presence of a text string, which the server will use, in appropriate situations, for constructing a text menu. Generation of this format is not supported as such by Map_This, although a simple programmatic conversion could be scripted from its "NCSA with comments" format into the Apache format.

See the relevant Apache documentation for a full description of what an Apache imagemap file may contain.

Migration from traditional NCSA to Apache (historical interest only)

The Rewrite Module guide's solution to this problem was:

    RewriteEngine  on
    RewriteRule    ^/cgi-bin/imagemap(.*)  $1  [PT]

but this only works if the image map file is already recognised by its type (filename-extension) in the server. In a situation where there are various imagemaps with no uniform naming scheme (perhaps with no filename extension), Joshua Slive pointed out a solution, which I tried and confirmed: modify the second line as follows

    RewriteRule  ^/cgi-bin/imagemap(.*)  $1  [PT,T=application/x-httpd-imap]

"Phantom imagemap" (historical interest)

A promising-looking idea was started by an Apache "contributed module": the "phantom imagemap" module mod_phantomimap, that offered to use a client-side imagemap in the HTML source file as its server-side imagemap. This looked to be the ideal low-effort way of getting server-side supported "on the back of" client-side for almost no effort from the HTML author. Unfortunately, the module was buggy as distributed, the author no longer reachable (around 1996-7). I guessed that (by 2002) client-side support was now so widespread that no-one really felt the motivation to pursue this: however, by chance I found that one provider actually offers this as a service to their customers (but they don't seem to be giving away their source code).

"CERN" imagemap format (historical interest only)

This format was defined by the W3C (ex-"CERN") httpd (now obsolete).

Summing up Server-side mapping

As we have seen, different servers (or to be pedantic, "different imagemap evaluators") may expect different formats of server-side imagemap. When selecting an imagemapping tool, it would be advisable (at least for authors who might move from one server to another) to ensure that the tool is able to read any kind of existing imagemap, and write it in an appropriate format for a different server.

About the only reasons I can think of for using server-side mapping nowadays from preference, is where the map areas must be kept secret (e.g a treasure hunt), or where the coordinates need to be fed to a complex algorithm rather than being a simple list of areas (but in that case you would also need a custom evaluator at the server, so you'd need CGI privileges).

Client-side Maps

The original specification for Client-side imagemaps was RFC1980. The currently-used version is essentially that given in HTML4.01. The HTML constructs are: MAP, and AREA, with their appropriate attributes.

Two shortcomings are present in some commonly used browsers:

These limitations have some negative implications:

Nevertheless, in view of the limitations in the deployed browser versions, I reluctantly advise you to use imagemaps in ways that comply with the limitations mentioned, i.e to send out the client-side map within the same file that references it, and before the (first) reference that uses it. Note that you might find it convenient to actually store the map separately at the server, and include it into the files that use it via the server-side include (SSI) mechanism: if you do so, then please try to ensure that it doesn't make your documents un-cacheable (on Apache, use the XBitHack Full option and set both user-execute and group-execute bits on the HTML files).

The following HTML fragment is appropriate for referencing a client-side imagemap:

<IMG SRC="URL-to-image" USEMAP="URL-to-csimap">

The IMG tag needs an appropriate ALT attribute, and normally also HEIGHT and WIDTH, in the usual way. The TITLE and LONGDESC are also available for promoting accessibility, in accordance with the principles of the WAI.

In view of the limitations already mentioned, the URL-to-csimap (the URL to the client side imagemap) will take the form #mapname, where mapname is the name specified on the NAME attribute of the MAP tag:

          <MAP NAME="mapname">
          <AREA ...>
          <AREA ...>

The above refers to versions of HTML proper. In XHTML, the map element has to be identified by the id attribute, although for transitional purposes, the same attribute value can be supplied on a name attribute also. We continue this tutorial on the basis of HTML for the time being.

The area shapes which are defined by the HTML4.01 specification are RECT, CIRCLE, POLY and DEFAULT. However, it appears that most (maybe all?) versions of MSIE do not support DEFAULT, so if you want your maps to work reliably with MSIE as well as with WWW-compatible browsers, you'd need to define, as the final item in the map, a RECT which covers the whole image, and use that as the default instead.

Unlike the server-side map, you can't "hide" this from text-mode users by coding ALT="", nor should you want to. Rather, you should be providing competent ALT attributes on the AREA tags of the MAP, so that the text-mode browser can construct a useful text-mode menu, and use the ALT attribute of the IMG to provide something meaningful to the text-mode user.

Overlapping areas

Some people have been going to extraordinary trouble to avoid their areas overlapping. This is definitely not necessary. Both server-side and client-side maps have made provision for overlapping areas, so if you wanted to have, say, some circular areas going to various different places, within a rectangle that goes to somewhere else, you can do so, easily. This technique can be seen in the example below.

Just keep in mind that the imagemap definitions (AREAs in the MAP, or directives in the server-side imagemap file) are processed in sequential order, and the first one which matches will be actioned. Therefore, if you have a number of overlapping areas, you want to define the "front" area of any overlap first in your imagemap file, and so on, with the rear-most area last, and then it will work as desired. Your imagemap utility program should get this right for you automatically, if it looks right visually (see the example later).

Putting it together

I'm not necessarily saying that you have to do this: modern browser/versions support client-side maps, and it's entirely up to you whether you think it's worth the effort to also cover browsers which can only do server-side mapping.

Blue circle (ALT) Green triangle (ALT) Red rectangle (ALT) Default area (ALT)

A dual-purpose client-side/server-side map can be constructed by combining the two syntaxes. A browser which supports the client-side functionality will use that in preference to using the server-side map.

The syntax, pretty obviously, is:

<A HREF="URL-for-mapping"><IMG SRC="URL-to-image" ISMAP USEMAP="#mapname"></A>

assuming that the client-side imagemap is in the same file, for the reason already given. Again the example omits the other attributes of the IMG tag, but please provide them as previously noted (the ALT attribute is mandatory according to standard HTML). As for the pure client-side map (and unlike the pure server-side map) you can't "hide" the dual map from text-mode users; rather, you should use it as explained in the associated text-friendly imagemaps article, so that useful text-mode menus get generated more or less "free of charge".

Whether ISMAP or USEMAP is placed first should not matter: RFC1980 gives an illustration in which the USEMAP attribute comes before the ISMAP, and this ordering is seen in other tutorials. However, one older browser was reported to ignore the ISMAP (which it could support) if it saw USEMAP first (which it couldn't). No browser has been reported to dislike finding the ISMAP first, so that is the ordering recomended here.

Sections 2.3 and 2.4 of RFC1980 describe both this and alternative ways of handling backwards compatibility, with examples. Of course, as all current browsers support at least a minimum subset of RFC1980 client-side imagemaps, there may be less need to worry about backwards compatibility.

Note that in the following example, the various texts are not intended to be taken as good examples of how to compose alternative text, titles etc.!! That topic is dealt with in another article; here, the wording has only been chosen so that you can recognise these texts, if and when you see them in a browser display, so that you know where they have come from.

(img alt example)

Frequently Asked Questions etc.

How can I use a [progressive JPEG, animated GIF, PNG image, etc] in an imagemap, if my imagemapping tool doesn't support this format?

No problem: just save the image at the identical size in a format that the imagemapping tool does support, make your imagemap, and then use that imagemap against the actual image that you want to use.

My AREA rectangle doesn't seem to be working...

The correct names for AREA shapes in client-side image maps are: rect, circle, poly and default. Some browsers support rectangle and polygon as shape names, thus giving the misleading impression that it's working, but this is not a standard, and will definitely cause problems in other browsers.


External imagemap file with server-side fallback?

Here's a thought: we know that some popular browsers don't support an external imagemap file for client-side imagemapping, but suppose that we provided a dual client-side/server-side map as described above. Would the incapable browsers fall back gracefully, and use the server- side map? Well, I investigated this in 1998, and I'm sorry to say that for some browser/versions, the answer is no.

NS3 or NS4 worked alright, ignoring the external client-side imagemap and using the server-side map instead. In MSIE3, the inclusion of an external imagemap reference prevented either kind of map working. In MSIE4, on the other hand, the external part of the reference was ignored, but if the current HTML document happened to contain a map with the same name, that was used instead!, i.e it used the wrong map. With WebTV viewer 1.0, again the presence of the external client-side imagemap reference stopped the map from working at all, as either kind of map. Of the browsers tested, only Opera worked as specified in the RFC; Lynx of course gives access to both the server-side and the client-side imagemap functions, so they both "work", in the sense that any imagemap can be said to work in Lynx.

Conclusion: it was a nice idea, but unfortunately, due to the behaviour of MSIE 3 and 4, and of WebTV viewer if this is representative of the behaviour of the "real" WebTV system, it's not of practical use on the WWW.

Other imagemap-like techniques

This section mentions, but without detail, a number of other imagemap-like techniques.


The INPUT TYPE=IMAGE element of the HTML FORM sends, along with the other data from the form, the x and y co-ordinates of the image click. This could therefore be used as an alternative to a server-side imagemap in some situations. However, whereas servers usually offer a server-side imagemap evaluator as standard, you would likely need a custom script for evaluating the results of such a form submission. Indeed, if you don't have CGI privileges you would not even be able to do that. And you would also need to design some useful kind of fallback for text-only situations.

FIG (from the expired HTML 3.0 draft)

The FIG element had a form of client-side imagemapping facility; however, it was never widely implemented.


The OBJECT element is specified in the HTML4.0 recommendation. Unfortunately, it's a paradox: the "best" support of this element is presently found in those browsers that don't recognise it at all, because it is designed to fall back gracefully on those, displaying whatever fallback you provided as the "content" of the OBJECT element. But, due to the horribly broken partial implementations that have appeared in browsers, you'd be running the risk that users of those browsers would get neither the intended object nor its fallback.

|Up|More | PPE Home|RagBag|About the author|Email|

Last changed Thursday, 02-Feb-2006 00:35:31 GMT