Getting Started

ImageMapster activates the areas in HTML Image MapsExternal link leaves this site so you can highlight and select them. It has lots of other features including tooltips, automatic resizing, and more. See ImageMapsters introduction to learn more about it’s features and history.

Installation

ImageMapster can be used with either jQuery or Zepto.

jQuery

NPM

This package can be installed via NPM:

npm install jquery imagemapster --save

Browser

Download the latest version of ImageMapster from the ReleasesExternal link leaves this site page and include in your webpage:

<!-- Optional: If targeting ES5 browers, as of ImageMapster v1.3.0, a Promise polyfill is required! -->
<script
  type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/es6-promise/dist/es6-promise.auto.min.js"
></script>
<script
  language="text/javascript"
  src="https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js"
></script>
<script language="text/javascript" src="jquery.imagemapster.min.js"></script>

Alternatively, you can include ImageMapster from one of the following CDNs:

Zepto

As of ImageMapster v1.3.2, ImageMapster contains full support for Zepto v1.2.0. The latest Zepto compatible version of ImageMapster is 1.8.0External link leaves this site.

Prior to ImageMapster v1.3.2 and with any version of Zepto except v1.2.0, ImageMapster is unlikely to work as expected. In the early versions of ImageMapster, Zepto support was maintained, however due to changes in Zepto, as of v1.2.5 of ImageMapster, support for Zepto compatability fell behind as it required too much effort and pushing ImageMapster forward with jQuery was the priority.

To use ImageMapster >= v1.3.2 < 2.0.0 with Zepto v.1.2.0, Zepto must contain the following Zepto ModulesExternal link leaves this site at a minimum:

zepto
event
ie
fx
touch
selector (required as of v1.5.0)

NPM - Zepto

The maintainers of Zepto decided not to support any module loaders so there is no official support of Zepto using AMD/CJS/etc. Given this, the Zepto version of ImageMapster expects a dependency of jquery when using a module loader. The Zepto version of ImageMapster will work with jQuery or Zepto. If you’d like to utilize Zepto, there are some projects that wrap Zepto and support UMD such as zepto-modulesExternal link leaves this site. In order to use Zepto, you will need to configure your bundler to map jquery to your Zepto build.

Using webpack and zepto-modules as an example:

Install from NPM

npm install zepto-modules imagemapster@1.8.0 --save

src/yourzepto.js

var $ = require('zepto-modules/zepto');

require('zepto-modules/event');
require('zepto-modules/ie');
require('zepto-modules/fx');
require('zepto-modules/touch');
require('zepto-modules/selector');

module.exports = $;

src/yourmodule.js

import $ from './yourzepto.js';
import im from 'imagemapster/dist/jquery.imagemapster.zepto.js';

$(yourImage).mapster({
  // your config here
});

webpack.config.js

module.exports = {
  resolve: {
    alias: {
      jquery: path.resolve('./src/yourzepto')
    }
  }
};

Browser - Zepto

Download the latest Zepto version of ImageMapster from the ReleasesExternal link leaves this site page and include in your webpage making sure to use jquery.imagemapster.zepto.min.js or jquery.imagemapster.zepto.js:

<!-- Optional: If targeting ES5 browers, as of ImageMapster v1.3.0, a Promise polyfill is required! -->
<script
  type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/es6-promise/dist/es6-promise.auto.min.js"
></script>
<script
  language="text/javascript"
  src="/path/to/your/custom/zeptodist"
></script>
<script
  language="text/javascript"
  src="/path/to/cdn/for/v1.8.0/dist/jquery.imagemapster.zepto.min.js"
></script>

Alternatively, you can include the Zepto version of ImageMapster from one of the following CDNs:

Basic Usage

Activate all image maps on the page with default options: on mouseover areas are highlighted with a gray fill with no border, and clicking an area causes it to become selected.

$('img[usemap]').mapster();

Activate all image maps on the page with some specific options.

$('img[usemap]').mapster({
  fillColor: 'ff0000',
  stroke: true,
  singleSelect: true
});

Methods

There are lots of ways to manipulate the image map from Javascript. Here are a few, see API Reference for complete documentation.

select: Cause an area to become “selected”

$('area').mapster('select');

Programatically select elements from the image map. The programmatic selection/deselection methods will not honor the staticState property.

deselect: Cause an area to become “deselected”

$('area').mapster('deselect');

set: select or deselect an element. If selected is true, the area is selected, if false, it is deselected.

$('area').mapster('set', selected);

You can also select or deselect areas using a their mapKey. This is an attribute on each area in your HTML that identifies it. You define a mapKey using a configuration option: mapKey: 'data-key'.

$('img[usemap]').mapster('set', true, 'key1,key2');

If two areas share the same value for the mapKey they will be automatically grouped together when activated. You can also use the values of the mapKey to select areas from code.

You can pass options to change the rendering effects when using set as the last parameter:

$('img[usemap]').mapster('set', true, 'key', { fillColor: 'ff0000' });

The value specified for mapKey can contain more than one value. The first value always defines groups when you mouse over. Other values can be used to create logical groups. For example:

<img id="usamap" src="map.jpeg" usemap="#usa" />
<map name="usa">
  <area data-key="maine,new-england,really-cold" shape="poly" coords="..." />
  <area
    data-key="new-hampshire,new-england,really-cold"
    shape="poly"
    coords="..."
  />
  <area data-key="vermont,new-england,really-cold" shape="poly" coords="..." />
  <area data-key="connecticut,new-england" shape="poly" coords="..." />
  <area data-key="rhode-island,new-england" shape="poly" coords="..." />
  <area data-key="massachusetts,new-england" shape="poly" coords="..." />
  <!-- more states... -->
</map>

$('#usamap').mapster({ mapKey: 'data-key' });

Mousing over each state would cause just that state to be highlighted. You can also select other logical groups from code:

// select all New England states
$('#usamap').mapster('set', true, 'new-england');

// select just Maine, New Hampshire & Vermont
$('#usamap').mapster('set', true, 'really-cold');

Groups created this way are independent of the primary group. If you select new-england from code, you can’t unselect just MA by clicking on it. You would have to unselect new-england from code.

To simply indentify a set of areas to turn on or off, but not treat them as a logical group, you can use CSS classes and select areas directly, or use the includeKeys option to identify the primary keys associated with a group.

Options

See configuration reference for complete documentation.