Image Hotspot

Turn any image into an interactive map: pins, circles and rectangles with tooltips, built and positioned in a visual editor inside WordPress.

1. Overview

Image Hotspot adds a Image Hotspots menu to your WordPress admin. Each entry there is one “map”: an image plus the markers you place on it. Every marker can carry a title, a description and a link. When the map is finished you copy a shortcode and paste it wherever the map should appear.

• Visual drag-and-drop editor — no coding at any point.
• Three marker types: pin, circle and rectangle.
• Tooltips open on click or on hover, in a dark or light theme.
• Positions are stored as percentages, so maps stay correct on every screen size.
• Markers are real buttons: reachable by keyboard, closable with Esc.
• CSS and JavaScript load only on pages that actually contain a map.
• No external services, no tracking, and no jQuery on the front end.

2. Requirements

3. Installation

From the WordPress admin

1. Go to Plugins → Add New → Upload Plugin.
2. Choose image-hotspot.zip and click Install Now.
3. Click Activate Plugin. A new Image Hotspots menu appears in the sidebar.

By FTP

1. Unzip the archive on your computer.
2. Upload the image-hotspot folder to /wp-content/plugins/.
3. Activate the plugin from Plugins in the admin.

4. Quick start

1. Go to Image Hotspots → Add New Map and give the map a name (this name is internal — visitors never see it).
2. Click Select image and pick an image from the media library, or upload a new one.
3. Click + Pin, + Circle or + Rectangle. The marker appears on the image and is selected automatically.
4. Drag the marker to the right spot. With a shape, drag the small square at its bottom-right corner to resize it.
5. Fill in Title, Tooltip text and, if you need one, a Link in the panel on the right.
6. Repeat for every marker, then click Publish.
7. Copy the shortcode from the How to display this map box in the sidebar and paste it into any post or page.

5. The editor

Toolbar

Canvas

The canvas is a live preview: what you see is what the visitor gets. Click a marker to select it, drag it to move it, and drag the handle at its bottom-right corner (shapes only) to resize it.

Keyboard shortcuts

Details panel

6. Hotspot types

A marker without a title and without tooltip text but with a link becomes a plain clickable area — useful for turning a diagram into a set of links.

7. Map settings

Settings apply to the whole map and are saved with it.

8. Displaying a map

Shortcode

[image_hotspot id="12"]

The exact shortcode for each map is shown in the How to display this map box on the map’s edit screen, and in the Shortcode column of the map list.

Attributes

[image_hotspot id="12" max_width="800"]

In a template file

<?php echo do_shortcode( '[image_hotspot id="12"]' ); ?>

<?php // or call the renderer directly:
echo IHS_Render::render( 12, array( 'max_width' => '800' ) ); ?>

Page builders

Any builder that supports shortcodes can display a map: use the block editor’s Shortcode block, Elementor’s Shortcode widget, WPBakery’s Text Block, or a shortcode-enabled widget.

9. Styling & CSS

All output is plain HTML with predictable class names, so it can be restyled from your theme or from Appearance → Customise → Additional CSS.

CSS custom properties

/* Bigger pins everywhere */
.ihs-map { --ihs-pin-size: 34px; }

/* Wider tooltips */
.ihs-tip { max-width: 340px; }

/* Square shapes instead of rounded ones */
.ihs-hs--rect .ihs-hs__target { border-radius: 0; }

Class reference

10. Developer reference

Data storage

A single hotspot looks like this. All coordinates are percentages of the image; for pins x/y is the centre, for shapes it is the top-left corner.

{
  "shape":   "pin",          // pin | circle | rect
  "x":       35,             // 0-100
  "y":       40,             // 0-100
  "w":       20,             // shapes only, 0-100
  "h":       20,             // shapes only, 0-100
  "color":   "#2563eb",
  "title":   "Living room",
  "content": "South-facing with oak flooring.",
  "link":    "https://example.com/gallery",
  "new_tab": 0
}

PHP

// Render a map anywhere in a template.
echo IHS_Render::render( int $map_id, array $args = array() );
// $args: [ 'max_width' => '800' ]

// Read raw data.
IHS_Data::get_image_id( $map_id );   // int
IHS_Data::get_hotspots( $map_id );   // array
IHS_Data::get_settings( $map_id );   // array

JavaScript

Maps initialise themselves on page load. If you inject a map with AJAX, re-run the initialiser afterwards:

window.ImageHotspot.init();

Uninstalling

Deactivating the plugin changes nothing. Deleting it from the Plugins screen permanently removes every map and its data, so export or back up first if you might need them again.

11. FAQ & troubleshooting

The shortcode shows as plain text

The map ID is missing or the shortcode is inside a block that does not process shortcodes. Use a Shortcode block, and check the ID against the map list.

“This map has no image yet”

The map was published before an image was chosen, or the image was deleted from the media library. Open the map, click Select image and update.

Nothing renders at all

Maps must be published — a draft renders nothing for visitors. Notices about broken maps are only visible to logged-in editors, never to visitors.

Markers sit in the wrong place

This happens when the theme crops the image (for example with object-fit: cover on all images). Add .ihs-map__image { object-fit: fill; height: auto; } to your custom CSS.

Tooltips are cut off at the edge

They should not be — a tooltip flips below the marker and shifts sideways to stay inside the image. If a theme sets overflow: hidden on the container, add .ihs-map__frame { overflow: visible; }.

Can I use the same map twice on one page?

Yes. Repeat the shortcode; each instance works independently.

Does it work with caching plugins?

Yes. The output is static HTML, so it caches like any other content.

12. Changelog & support

1.0.0

• Initial release.

For support, contact the author through the marketplace item page. When reporting a problem, please include your WordPress version, PHP version, active theme and a link to the page showing the map.