Image Hotspot Plugin

A Strapi v5 plugin that provides a custom field for adding interactive hotspots (points and rectangles) to images with various action types.

Preview

Features

• Image Selection: Select images from the media library via modal dialog
• Point Hotspots: Add point hotspots by clicking on the image
• Rectangle Hotspots: Add rectangle hotspots by clicking and dragging
• Hotspot Management: Drag, resize, and delete hotspots
• Visual Feedback: Visual indicators for selected hotspots
• Multiple Action Types: Configure actions for each hotspot:
  • Link: Navigate to a URL (with target options)
  • Modal: Display content in a modal dialog
  • Tooltip: Show tooltip text on hover
  • Callback: Execute custom JavaScript functions
  • None: No action
• Automatic Image Population: Server-side middleware automatically populates image fields in API responses, so you get full image objects instead of just IDs

Installation

This plugin is automatically loaded by Strapi when placed in the src/plugins directory.

Server-Side Features

The plugin includes server-side middleware that automatically:

• Intercepts API responses for content types using the image-hotspot field
• Populates image references with full media objects (including URL, alternative text, etc.)
• Works with both single entity and collection responses

This means when you fetch data via the API, the image field in your hotspot data will already contain the full media object, not just an ID.

Usage

Adding to Content Type Schema

In your content type schema, use:

1{
2  "attributes": {
3    "imageHotspot": {
4      "type": "customField",
5      "customField": "plugin::image-hotspot::image-hotspot"
6    }
7  }
8}

Action Types

Link Action

Navigate to a URL when the hotspot is clicked:

• url: The target URL
• target: "_self" (same tab) or "_blank" (new tab)

Modal Action

Display content in a modal dialog:

• modalTitle: Title of the modal
• modalContent: Content to display in the modal

Tooltip Action

Show tooltip text on hover:

• tooltipText: Text to display in the tooltip

Callback Action

Execute a custom JavaScript function when the hotspot is clicked:

• callbackName: Name of the function to call (e.g., "handleHotspotClick")
• callbackParams: JSON object with parameters to pass to the function

Example:

1{
2  "type": "callback",
3  "callbackName": "handleHotspotClick",
4  "callbackParams": {
5    "hotspotId": "123",
6    "action": "navigate"
7  }
8}

On the frontend, you would implement the callback function:

1window.handleHotspotClick = function (params) {
2  console.log("Hotspot clicked with params:", params);
3  // Your custom logic here
4};

Using in Frontend

When rendering the image with hotspots on your frontend, you'll need to:

1. Parse the JSON data from the custom field
2. Render the image (the image object is automatically populated by the server)
3. Position hotspots based on their coordinates
4. Handle click events based on the action type

Note: The server automatically populates the image field with the full media object, so you can directly access data.image.url without needing to fetch the media separately.

Example React component:

1import { ImageHotspotValue } from "./types";
2
3function HotspotImage({ data }: { data: ImageHotspotValue }) {
4  const handleHotspotClick = (hotspot: Hotspot) => {
5    if (!hotspot.action) return;
6
7    switch (hotspot.action.type) {
8      case "link":
9        if (hotspot.action.url) {
10          window.open(hotspot.action.url, hotspot.action.target || "_self");
11        }
12        break;
13      case "modal":
14        // Show modal with hotspot.action.modalTitle and hotspot.action.modalContent
15        break;
16      case "tooltip":
17        // Show tooltip with hotspot.action.tooltipText
18        break;
19      case "callback":
20        if (
21          hotspot.action.callbackName &&
22          window[hotspot.action.callbackName]
23        ) {
24          window[hotspot.action.callbackName](hotspot.action.callbackParams);
25        }
26        break;
27    }
28  };
29
30  return (
31    <div className="hotspot-container">
32      <img src={data.image?.url} alt={data.image?.alternativeText} />
33      {data.hotspots?.map((hotspot) => (
34        <div
35          key={hotspot.id}
36          className={`hotspot hotspot-${hotspot.type}`}
37          style={{
38            left: `${hotspot.x}%`,
39            top: `${hotspot.y}%`,
40            width: hotspot.width ? `${hotspot.width}%` : undefined,
41            height: hotspot.height ? `${hotspot.height}%` : undefined,
42          }}
43          onClick={() => handleHotspotClick(hotspot)}
44        >
45          {hotspot.label}
46        </div>
47      ))}
48    </div>
49  );
50}

License

MIT