Click to toggle dark text on white

Mapbox: Zoomable jQuery Map Plugin

Click here for the mapbox.min.js code - Click here for the uncompressed code

$().mapbox(). Version 0.5

The jQuery mapbox() plugin is for creating relatively small scale, zoomable, draggable maps with multiple layers of content. This framework could be applied to games, development plans, or any layout that could benefit from being able to zoom in and pan to get a better view.

Mousewheel will zoom the map. Drag to pan.

* New feature: by default, the map will now zoom to the cursor position when the mousewheel is used. This is an intuitive means by which a user may explore different areas of the map.

The code:
Before using Mapbox, you must link to jQuery and mapbox.js. I do this in the HEAD of my document. I always use the minified jQuery that is hosted by Google. Also, if you want the map's zoom to be activated by the mousewheel, you must include the mousewheel plugin:

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

Then, some CSS. This is how I styled the map in this example, though you may use any rules you like (the Middle Earth map has an odd proportion):

<style type="text/css"> 
    #viewport { 
        width: 469px
        height: 400px
        cursor: move
        margin: 20px auto
        overflow: hidden/*keep map contents from spilling over if JS is disabled*/ 

Then, some HTML. The structure of your map must be almost exactly like this, though you may have as many or few layers as you wish. I recommend at least 2. Every layer DIV must have a height and width set to it. I did it inline in this example only for ease of understanding. IMG tags must be used for every layer except the starting one, which you should notice is structured much differently than the other layers. You currently must include the .mapcontent class on the inner layers, even if you aren't planning to add additional content to the map:

<div id="viewport"> 
    <div style="background: url(images/layer1.png) no-repeat; width: 469px; height: 400px;"> 
        <!--top level map content goes here--> 
    <div style="height: 1097px; width: 1286px;"> 
        <img src="images/layer2.jpg" alt="" /> 
        <div class="mapcontent"> 
            <!--map content goes here--> 
    <div style="height: 1794px; width: 2104px;"> 
        <img src="images/layer3.jpg" alt="" /> 
         <div class="mapcontent"> 
            <!--map content goes here--> 
    <div style="height: 2492px; width: 2922px;"> 
        <img src="images/layer4.jpg" alt="" /> 
         <div class="mapcontent"> 
            <!--map content goes here--> 

The jQuery:

<script type="text/javascript"
    $(document).ready(function() { 
        $("#viewport").mapbox({mousewheel: true}); 

That is all! (requires mousewheel plugin: If you don't require the mousewheel, the map may be created simply as $("#viewport").map(). Of course, there are some more advanced settings. Here are all of the settings and their defaults:

<script type="text/javascript"
        zoom: true, // does map zoom? 
        pan: true, // does map move side to side and up to down? 
        defaultLayer: 0// starting at 0, which layer shows up first 
        layerSplit: 4// how many times to split each layer as a zoom level 
        mapContent: ".mapcontent"// the name of the class on the content inner layer 
        defaultX: null, // default positioning on X-axis 
        defaultY: null, // default positioning on Y-axis 
        zoomToCursor: true, // if true, position on the map where the cursor is set will stay the same relative distance from the edge when zooming 
        doubleClickZoom: false, // if true, double clicking zooms to mouse position 
        clickZoom: false, // if true, clicking zooms to mouse position 
        doubleClickZoomOut: false, // if true, double clicking zooms out to mouse position 
        clickZoomOut: false, // if true, clicking zooms out to mouse position 
        doubleClickMove: false, // if true, double clicking moves the map to the cursor position 
        clickMove: false, // if true, clicking moves the map to the cursor position 
        doubleClickDistance: 1// number of positions (determined by layerSplit) to move on a double-click zoom event 
        clickDistance: 1// number of positions (determined by layerSplit) to move on a click zoom event 
        callBefore: function(layer, xcoord, ycoord, viewport) {}// this callback happens before dragging of map starts 
        callAfter: function(layer, xcoord, ycoord, viewport) {}// this callback happens at end of drag after map is released "mouseup" 
        beforeZoom: function(layer, xcoord, ycoord, viewport) {}// callback before a zoom happens 
        afterZoom: function(layer, xcoord, ycoord, viewport) {}// callback after zoom has completed 
        mousewheel: false /* requires mousewheel event plugin:*/ 


In addition to the settings, there are some methods that may be passed to any map once it has been created:

<script type="text/javascript"
    $("#viewport").mapbox("zoom");//zooms in 1 level (determined by layerSplit option) 
    $("#viewport").mapbox("zoom"2);//zooms in 2 levels 
    $("#viewport").mapbox("back");//zooms out 1 level 
    $("#viewport").mapbox("back"2);//zooms out 2 levels 
    $("#viewport").mapbox("zoomTo"2);//zooms to the default size of the third layer (0 being the first) 
    $("#viewport").mapbox("left");//move the current layer left 10 pixels 
    $("#viewport").mapbox("right");//move the current layer right 10 pixels 
    $("#viewport").mapbox("up");//move the current layer up 10 pixels 
    $("#viewport").mapbox("down");//move the current layer down 10 pixels 
    $("#viewport").mapbox("left"20);//move the current layer left 20 pixels 
    $("#viewport").mapbox("right"20);//move the current layer right 20 pixels 
    $("#viewport").mapbox("up"20);//move the current layer up 20 pixels 
    $("#viewport").mapbox("down"20);//move the current layer down 20 pixels 
    $("#viewport").mapbox("center");//centers current layer 
        x: 200
        y: 400 
    });//centers current layer at positions 200px, 400px on the x and y axis 

Here's an example using some of these methods to implement a control panel for the map:

    jQuery(document).ready(function() { 
            mousewheel: true, 
            layerSplit: 8//smoother transition for mousewheel 
        jQuery(".map-control a").click(function() {//control panel 
            var viewport = $("#viewport2"); 
            //this.className is same as method to be called 
            if(this.className == "zoom" || this.className == "back"{ 
                viewport.mapbox(this.className, 2);//step twice 
            else { 
            return false; 

The JavaScript error on this page is due to the Chili (code highligher) plugin. It is not due to a conflict with mapbox, and is an exception triggered in jQuery's each() function. Anyone care to help me figure out what is going on? (use my contact form)

Click here for the mapbox.min.js code - Click here for the uncompressed code

Most Recent Blog Post: Introducing WowWindow

Privacy Policy | Click Here | jQuery Plugins by Wayfarer | Freelance Jobs Available | Random JavaScript Code Samples | Share a Random Link | JavaScript Jobs