mapzoom.js 1.4 allows you to add zoom and pan functionality to oversized images/vectors and automatic area highlighting to image maps on your webpages. It's a conceptual combination of ShiftZoom and Mapper. It also allows you to build interactive applications through the various user commands. It uses unobtrusive javascript to keep your code clean.

It works in all the major browsers - Mozilla Firefox 3+, Safari 3.1+, Chrome 5+, IE 6+ and Opera 9.5+. Works also on older browsers supporting images/ createElement/ getElementById but without vector support, else it'll degrade and your visitors won't notice a thing.


Egypt Ethiopia Algeria Benin Botswana Burundi Burkina Faso Democratic Republic of the Congo Djibouti Ivory Coast Eritrea Gabon Gambia Ghana Guinea Guinea-Bissau Cameroon Kenya Libya Liberia Madagascar Mali Malawi Morocco Mauritania Mozambique Namibia Niger Nigeria Republic of the Congo Rwanda Zambia Senegal Sierra Leone Zimbabwe Somalia Sudan South Africa Swaziland Tanzania Togo Tunisia Chad Uganda Western Sahara Central African Republic Lesotho Equatorial Guinea Angola Angola
Images used are copyrighted by Creative Commons or other free / fair use licenses and were used for demonstration only.

Setting Up

Download mapzoom.js and include it into your webpages HEAD section.

<script type="text/javascript" src="mapzoom.js"></script>

// only if the cursor images for IE are not in the current path
<scriptscript type="text/javascript">

Using It

To add mapzoom just set the event onload="mapzoom.add(this);" to a div surrounded image.

To get individual area highlightings, add one or more classes to the image map area.

<area shape="poly" class="noborder vacolor00ff00" href="#" coords="...">

To get multiple area selections, add one or more id's to the areas rel attribute.

<area shape="poly" id="blue" rel="green,red" href="#" coords="...">
<area shape="poly" id="green" rel="red,blue" href="#" coords="...">
<area shape="poly" id="red" rel="green,blue" href="#" coords="...">

To force a group of areas using the attributes of the initial area.

<area shape="rect" id="black" class="forcegroup vacolor000000" rel="green,red,blue" href="#" coords="...">

To subtract one or more areas from another one, add the id's to the areas rev attribute.

<area shape="poly" id="red" rev="green,blue" href="#" coords="...">
<area shape="poly" id="blue" href="#" coords="...">
<area shape="poly" id="green" href="#" coords="...">

Add one or more classes to the image map area, to set individual preselection values.

<area shape="poly" class="specified pacolor00ff00 pbacolorfffff vaopacity50 vbopacity75" href="#" coords="...">



Mouse- and Keyboard-driven handling:

shiftleft mouse  zoom in    mouse wheel  zoom in    middle mouse  zoom in* 
altleft mouse  zoom out    mouse wheel  zoom out    right mouse  zoom out* 
* must be set through preferences by Firefox and Opera (gecko/presto)

Keyboard-driven handling: (if focused through mouse over image)

left  pan left    shiftleft  pan left (fast)    altleft  pan left (slow) 
right  pan right    shiftright  pan right (fast)    altright  pan right (slow) 
up  pan up    shiftup  pan up (fast)    altup  pan up (slow) 
down  pan down    shiftdown  pan down (fast)    altdown  pan down (slow) 
plus  zoom in*    end  zoom in (fast)    pgdn  zoom in 
minus  zoom out*    home  zoom out (fast)    pgup  zoom out 
* not supported by Firefox and Opera (gecko/presto)

Stick/Finger-driven handling: (touch events)


Set defaults
mapzoom.defaultCallback   = null; //STR simple callback function
mapzoom.defaultFading     = true; //BOOLEAN startup image fading
mapzoom.defaultButtons    = true; //BOOLEAN left top buttons
mapzoom.defaultNozoom     = false; //BOOLEAN disable zooming feature
mapzoom.defaultBicubic    = false; //BOOLEAN enable bicubic image interpolation for IE7+
mapzoom.defaultWheelinvert= false; //BOOLEAN makes zoom behaviour identical with Google Maps
mapzoom.defaultWheelstep  = 20; //INT/FLOAT 0-100 (%) wheel step size percentage
mapzoom.defaultZoom       = 0; //INT/FLOAT 0-100 (%) zooming percentage
mapzoom.defaultXpos       = 50; //INT/FLOAT 0-100 (%) horizontal position
mapzoom.defaultYpos       = 50; //INT/FLOAT 0-100 (%) vertical position
mapzoom.defaultOpacity    = 70; //INT 0-100 (%) zoom button opacity
mapzoom.defaultMillisec   = 30; //INT 5-100 zoom interval delay
mapzoom.defaultIntitle    = 'zoom in'; //STR zoom in button title text
mapzoom.defaultOuttitle   = 'zoom out'; //STR zoom out button title text
mapzoom.defaultInfoblock  = '<dl>...<\/dl>'; //STR Info/Help block content
mapzoom.defaultCurpath    = ''; //STR cursor path (*.cur) IE only
mapzoom.defaultLowres     = ''; //STR lowres image (dimension equals elements width and height)
mapzoom.defaultIcons      = null; //OBJ icon array (see mapzoom.construct)
mapzoom.defaultShowcoords = false; //BOOLEAN show coordinates
mapzoom.defaultRelativecoords=false; //BOOLEAN relative instead of absolute pixel coordinates
mapzoom.defaultPixelcoords= true; //BOOLEAN show Pixel coords instead of Lat/Lon
mapzoom.defaultPercentcoords=false; //BOOLEAN show percentage instead of Lat/Lon/Pixel coordinates
mapzoom.defaultForcetouchui=false; //BOOLEAN forces touch UI over the mouse UI if both available
mapzoom.defaultOverview   = true; //BOOLEAN show overview
mapzoom.defaultOvsfact    = 25; //INT 10-50 (%) overview size factor
mapzoom.defaultOvaopac    = 75; //INT 0-100 (%) overview area opacity
mapzoom.defaultOvacolor   = 'red'; //STR overview area css color
mapzoom.defaultOvbcolor   = 'white'; //STR overview border css color
mapzoom.defaultOvborder   = ''; //INT 0-20 (px) or "" overview border width
mapzoom.defaultPvaopac    = 33; //INT preselection vector area opacity 0-100 (%)
mapzoom.defaultPvbopac    = 66; //INT preselection vector border area opacity 0-100 (%)
mapzoom.defaultPvacolor   = '#ffffff'; //STR preselection vector area color '#000000'-'#ffffff'
mapzoom.defaultPvbcolor   = '#808080'; //STR preselection vector border color '#000000'-'#ffffff'
mapzoom.defaultVaopac     = 33; //INT vector area opacity 0-100 (%)
mapzoom.defaultVbopac     = 66; //INT vector border opacity 0-100 (%)
mapzoom.defaultVbwidth    = 80; //INT vector border width 20-100 (%)
mapzoom.defaultVbcolor    = '#000000'; //STR vector border color '#000000'-'#ffffff'
mapzoom.defaultVacolor    = '#0000ff'; //STR vector area color '#000000'-'#ffffff'
mapzoom.defaultVnborder   = false; //BOOLEAN vector area no border (true or false)
mapzoom.defaultVafading   = false; //BOOLEAN vector area fading (true or false)

Add functionality to image
mapzoom.add(image[, options]);
image  == div surrounded image
options         e.g. {overview: true, opacity: 32, ...}
callback   == STRING null or 'myFunction' Default: null
fading     == BOOLEAN true or false Default: true
buttons    == BOOLEAN true or false Default: true
nozoom     == BOOLEAN true or false Default: false
bicubic    == BOOLEAN true or false Default: false
wheelinvert== BOOLEAN true or false Default: false
wheelstep  == INT/FLOAT 0 - 100 Default: 20
zoom       == INT/FLOAT 0 - 100 Default: 0
xpos       == INT/FLOAT 0 - 100 Default: 50
ypos       == INT/FLOAT 0 - 100 Default: 50
opacity    == INT 0 - 100 Default: 90
millisec   == INT 5 - 100 Default: 40
intitle    == STRING Default: 'click or press shift key to zoom in'
outtitle   == STRING Default: 'click or press alt key to zoom out'
infoblock  == STRING Default: '<dl>...<\/dl>'
curpath    == STRING Default: ''
lowres     == STRING Default: '' (faster zooming)
icons      == OBJECT Default: null (icon array)
showcoords == BOOLEAN true or false Default: false
relativecoords==BOOLEAN true or false Default: false
pixelcoords== BOOLEAN true or false Default: true
percentcoords==BOOLEAN true or false Default: false
forcetouchui==BOOLEAN true or false Default: false
overview   == BOOLEAN true or false Default: true
ovsfact    == INT 10 - 50 Default: 25
ovaopac    == INT 0 - 100 Default: 75
ovacolor   == STRING '#ffaa00' or 'orange' Default: 'red'
ovbcolor   == STRING '#0000ff' or 'blue' Default: 'white'
ovborder   == INT 0 - 20 Default: automatic pvaopac    == INT 0 - 100 Default: 33
pvbopac    == INT 0 - 100 Default: 66
pvacolor   == '#000000' to '#ffffff' Default: '#ffffff'
pvbcolor   == '#000000' to '#ffffff' Default: '#808080'
vaopac     == INT 0 - 100 Default: 33
vbopac     == INT 0 - 100 Default: 66
vbwidth    == INT 20 - 100 Default: 80
vbcolor    == '#000000' to '#ffffff' Default: '#000000'
vacolor    == '#000000' to '#ffffff' Default: '#0000ff'
vnborder   == BOOLEAN true or false Default: false
vafading   == BOOLEAN true or false Default: false

Get some informations
FLOAT|INT = mapzoom.get(image, ['maxzoomx'|'maxzoomy'|'maxwidth'|'maxheight']);
BOOLEAN = mapzoom.get(image,'playing');
BOOLEAN = mapzoom.get(image,'vectorsupport');
OBJECT = mapzoom.get(image,'currentxyz');
(returns current x=xpos, y=ypos and z=zoom values as INT/FLOAT 0-100 (%))
FLOAT = mapzoom.version;
STRING = mapzoom.released;

Convert Lat/Long to Pixel value
mapzoom.findpxpos(image, latitude, longitude, type [, imagewidth, elementwidth, imageheight, elementheight, coordbox]);
image  == mapzoom element
latitude      == x position as float -90.0 - 90.0 mandatory
longitude     == y position as float -180.0 - 180.0 mandatory
type          == type of object is "area" or "icon" mandatory
imagewidth    == optional natural image width
elementwidth  == optional element width
imageheight   == optional natural image height
elementheight == optional element height
coordbox      == optional [90, -180, -90, 180]
(returns x=xpos, y=ypos values as FLOAT)

Modify some defaults
mapzoom.set(image, ['buttons'|'overview'|'showcoords'|'relativecoords'|'pixelcoords'|'zoomin'|'zoomout'|'nozoom'], [true|false]);
(The external zoom button control zoomin|zoomout depends on the settings buttons=false and nozoom=false)

Modify current infoblock, value);
value == innerHTML-block (e.g. '<dl>...<\/dl>')

Modify current source image
mapzoom.source(image, value, boolean);
value == URI (e.g. 'images/world.jpg')
boolean == fade out/in (true or false)

Modify current lowres source image
mapzoom.lowsource(image, value);
value == URI (e.g. 'images/world_lowres.jpg')

Modify current zooming
mapzoom.zooming(image, value);
value == 0 - 100 (%) default: 0

Modify current position
mapzoom.moveto(image, x, y);
x,y default: 0,0
if x or y == INT e.g. 189
then it's interpreted as pixel from within natural image dimension

if x or y == STR e.g. '50%' Pattern: (INT|FLOAT)%
then it's interpreted as percentage

if x or y == STR e.g. '-23.057' Pattern: (+|-)(INT|FLOAT)
then it's interpreted as longitude or latitude

Modify current position and zoom (animated)
mapzoom.kenburns(image, [x, y, z, e, s, d, c, a]);
x == left position 0 - 100 (%) default: 50
y == top position 0 - 100 (%) default: 50
z == zomm factor 0 - 100 (%) default: 50
e == optional progression 0.0 - 2.0 | 3 default: 1
    [< 1 == ease-out | 1 == linear | > 1 == ease-in | 3 == ease-in-out]
s == optional animation steps 10 - 100 default: max distance/interval delay
d == optional interval delay 10 - 100 default: 30
c == optional callback function name (executes on end of animation) default: ''
a == optional callback argument (string or number only) default: ''
(To use callback and default values for e, s, d set e, s, d to false)

Start playing, delay, loop, array, callback);
delay    == delay between play positions 0 - 100000 millisec. default: 0
loop     == loop array true or false default: false
array    == two dimensional array with syntax from kenburns [[x,y,z], [x,y,z,e], [x,y,z,e,s], [x,y,z,e,s,d]...]
callback == optional function name (executes on stop playing)
(Start playing will set buttons, showcoords, overview to false and nozoom to true)

Stop playing
(Stop playing is also executed on user action through mouse or keyboard)

Add icon(s) to image
mapzoom.construct(image, object);
object         e.g. [{x: 52, y: 31, ...},{...}]
x      == x position relative to images natural width 0 - n (px) Default: 0
y      == y position relative to images natural height 0 - n (px) Default: 0
w      == icon width 8 - n (px) Default: 0
h      == icon height 8 - n (px) Default: 0
src    == icon #1 image URL Default: ''
src2   == optional icon #2 image URL Default: ''
pos    == optional icon position 0 - 9 Default: 0 (1=left-top, 2=center-top, 3=right-top, 4=center-left, 0/5=center-center, 6=center-right, 7=left-bottom, 8=center-bottom, 9=right-bottom)
id     == optional icon id Default: ''
title  == optional icon tooltip text Default: ''
href   == optional icon link URL Default: ''
target == optional icon link target Default: ''

Modify icon image
mapzoom.restruct(image, icon-id, options);
options         e.g. {href: '', ...}
title  == icon tooltip text Default: ''
href   == icon link URL Default: ''
target == icon link target Default: ''

Remove icon(s) from image
mapzoom.destruct(image, value);
value == STRING (remove named icon)
value == BOOLEAN (remove all icons)

Set vector area highlight on
mapzoom.areaover(image, area-id);

Set vector area highlight off
mapzoom.areaout(image, area-id);

Remove vector area(s)
mapzoom.deletearea(image, value);
value == STRING (remove named area)
value == BOOLEAN (remove all areas)

Add vector area
mapzoom.createarea(image, area-id, options);
options         e.g. {coords: 10,10,100,100, ...}
shape    == shape type (rect|circle|ellipse|polygon|poly|path|polyline|line) Default: 'poly'
coords   == coordination array Default: [] relative to elements dimensions
rel      == array of area-id's to show synchronous Default: []
rev      == array of area-id's to subtract from this (must be polyline) Default: []
tooltip  == optional area html tooltip Default: ''
alttitle == optional area alt and title text Default: ''
href     == optional area link URL Default: ''
target   == optional area link target Default: ''
classes  == optional area classes(vbdash10, vbwidth100, vbcapround, vbcapflat, vbopacity00, vbcolor000000, vaopacity00, vacolor000000, paopacity00, pbopacity00, pacolor000000, pbcolor000000, noborder, specified, forcegroup) Default: ''
vbdash + 0==solid, 1==shortdot, 2==dot, 3==shortdash, 4==dash, 5==longdash ,6==shortdashdot ,7==dashdot ,8==longdashdot ,9==shortdashdotdot, 10==longdashdotdot
vbdash0-10 with vbcapround and vbcapflat:

Modify vector area
mapzoom.modifyarea(image, area-id, options);
options         e.g. {coords: 10,10,100,100, ...}
coords   == coordination array Default: [] relative to elements dimensions
rel      == array of area-id's to show synchronous Default: []
rev      == array of area-id's to subtract from this (must be polyline) Default: []
tooltip  == optional area html tooltip Default: ''
alttitle == optional area alt and title text Default: ''
href     == optional area link URL Default: ''
target   == optional area link target Default: ''
classes  == optional area classes (vbopacity100, vbcolor000000, vbdash10, vbwidth100, vbcapround, vbcapflat, vacolor000000, vaopacity100, paopacity100, pbopacity100, pacolor000000, pbcolor000000, noborder, specified, forcegroup) Default: ''

Remove functionality from image
mapzoom.remove(image, value);
value == BOOLEAN (reset image to natural dimension)

<img onLoad="mapzoom.add(this);" ...>
if(typeof $=='undefined') {function $(v) {return(document.getElementById(v));}}
mapzoom.add($('img'), {fading:false, curpath:'cursors/'});
<button type="button" onclick="mapzoom.set($('img'),'zoomin',true);"> + </button>
<button type="button" onclick="mapzoom.set($('img'),'zoomout',true);"> - </button>
alert('mapzoom: '+mapzoom.version+' ('+mapzoom.released+')');$('img'),'<p>eat my shorts<\/p>');

If you need utility functions, use "maputil.js". You can generate SVG files out of Image maps.

makeSVGfromMap(map, options);
map should be a map element: document.getElementsByName("myimg")[0]
options (contains zero or more values)
output e.g. true (return svg document) | false (open window with source)
width e.g. 502 (image width as pixel value)
height e.g. 482 (image height as pixel value)
stroke-width e.g. 0.75 | default 0.5 px
stroke-miterlimit e.g. 8 | default 1
initialfillcolor e.g. #cccccc | default silver
initialstrokecolor e.g. #808080 | default gray
hoverfillcolor e.g. #66ff66 | default limegreen
hoverstrokecolor e.g. #00ff00 | default green
backgroundcolor e.g. #ffffff | default null
<a href="#" onClick="makeSVGfromMap(document.getElementsByName("myimg")[0],false,502,482);">Generate SVG</a>
makeSVGfromMap() parses the style attribute of <area /> tags for fill and stroke styles to complete the SVG!

scaleMapAreaCoords(map, nw, nh, sw, sh, options);
map should be a map element: document.getElementsByName("myimg")[0]
nw = width e.g. 800 (natural image width as pixel value)
nh = height e.g. 400 (natural image height as pixel value)
sw = width e.g. 400 (scaled image width as pixel value)
sh = height e.g. 200 (scaled image height as pixel value)
options (contains zero or more values)
arg1 xoff e.g. -2 (horizontal offset as pixel value)
arg2 yoff e.g. -2 (vertical offset as pixel value)
scaleMapAreaCoords() opens a window with the source!

Why use Javascript mapzoom?

In very old browsers, the script degrades and your visitors won't notice a thing.


Please read the license before you download mapzoom.js 1.4


Please read the Frequently Asked Questions before you contact the author.


Element dimensions should always respect the Aspect Ratio of the image.

iOS (iPod/iPad/iPhone) Resource Limits (Quote):
"JPEG images can be up to 32 megapixels due to subsampling, which allows JPEG images to decode to a size that has one sixteenth the number of pixels. JPEG images larger than 2 megapixels are subsampled—that is, decoded to a reduced size. JPEG subsampling allows the user to view images from the latest digital cameras."

Android zooming (pinch gesture). Currently not, because android emulator do not support multiple finger gestures!

Internet Explorer's image scaling through bicubic interpolation is only available in version 7 and up. So don't expect to much (smooth display) from older browsers like IE 5, IE 5.5, and IE 6. IE needs external cursor images (*.cur). IE 6/7/8 do neither support vector borders nor vector fading.

Opera and old Safaris are unable to interpret style sheet percentages properly and exactly.

Handling javascript mouse events is not a simple thing, because there are inconsistancies in the way different browsers implement mouse events. That's the reason why the response on right mouse button is inconsistent in mapzoom. With Opera it's impossible to prevent the context menu from showing up.


Version 1.4

Version 1.3 Version 1.2 Version 1.1 Version 1.0


Please leave any comments at this contact formular.


mapzoom.js is distributed under the Netzgestade Non-commercial Software License Agreement.
License permits free of charge use on non-commercial and private web sites only under special conditions (as described in the license). This license equals neither "open source" nor "public domain". There are also Commercial Software Licenses available.


Other Projects © 2024 by Christian Effenberger :: Imprint feed   twitter   facebook   myspace   delicious   digg   reddit   magnoliacom   newsvine   furl   google   yahoo   blinklist   mister-wong