react-hotspot-viewer-image

react-hotspot-viewer-image

A React component that displays interactive hotspots over an image with an animated “ping” effect. On desktop, clicking a hotspot shows a tooltip with title and description; on mobile, it opens a Shadcn UI Drawer. Hotspots maintain their relative positions responsively as the image resizes.

Features

• Animated Hotspots: Pulsing “ping” animation behind each hotspot pin.
• Desktop Tooltips: Click a hotspot to open a styled tooltip; click outside or the close icon to dismiss.
• Mobile Drawers: On screens ≤768px, hotspots open a Shadcn UI Drawer for title and description.
• Responsive: Positions are percentage-based and adjust with image resizing.
• Zero Dependencies: Only relies on peer dependencies.

Installation

Install via npm or yarn:

# npm
npm install react-hotspot-viewer-image

# yarn
yarn add react-hotspot-viewer-image

Peer Dependencies

Ensure the following are installed in your project:

• react ^17 || ^18
• react-dom ^17 || ^18
• @shadcn/ui (for the Drawer component)
• (Optional) tailwindcss >=3.0.0 if you use Tailwind in your app
• (Optional) class-variance-authority, lucide-react if you extend styling/icons

Usage

Import the component and provide an array of hotspots:

import React from 'react';
import { HotspotViewer, Hotspot } from 'react-hotspot-viewer-image';

const hotspots: Hotspot[] = [
  {
    id: 1,
    title: 'Title 01',
    description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',
    position: { top: '30%', left: '50%' },
  },
  {
    id: 2,
    title: 'Title 02',
    description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',
    position: { top: '20%', left: '80%' },
  },
  // add more hotspots as needed...
];

export default function App() {
  return (
    <div style={{ maxWidth: '800px', margin: '0 auto' }}>
      <HotspotViewer
        hotspots={hotspots}
        imageSrc="/your/image/path.jpg"
      />
    </div>
  );
}

Props

hotspots (required)

Type: Hotspot[]

Array of hotspot objects:

| Property | Type | Description | | ----------- | ------------------- | ---------------------------------------------------------------- | | id | number | Unique identifier for each hotspot. | | title | string | Title displayed in the tooltip or drawer header. | | description| string | Text displayed in the tooltip body or drawer description. | | position | { top: string; left: string; } | CSS values (% or px) for positioning relative to the image. |

imageSrc (optional)

Type: string Default: '/img/suplemento-premiado/section-05-thumb.svg'

URL or path to the base image over which hotspots are placed.

Configuration & Styling

• The component uses styled-jsx for scoped styles. To customize, you can:
  • Pass a different imageSrc.
  • Override CSS variables or target .hotspot-tooltip, .hotspot-pin, .hotspot-ping in your global styles.
• Ensure your project supports client components (e.g., Next.js 13+ with use client).

Development

1. Clone the repo

   git clone https://github.com/your-username/react-hotspot-viewer-image.git
   cd react-hotspot-viewer-image

2. Install dependencies

   npm install

3. Build

   npm run build

4. Link locally (for testing in another project)

   npm link

Contributing

Contributions, issues, and feature requests are welcome! Please follow the standard gitflow:

1. Fork the repository.
2. Create a feature branch: git checkout -b feat/my-new-feature
3. Commit your changes: git commit -m 'Add some feature'
4. Push to the branch: git push origin feat/my-new-feature
5. Open a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.