React Image Section Mapper

A TypeScript React component for creating interactive, resizable, and draggable sections on images. Perfect for creating image maps, hotspots, or annotated areas on images.

Features

• 🎯 Create clickable sections on images
• 🖱️ Drag & resize sections with handles
• 📱 Responsive design
• 🎨 Customizable themes
• 💾 Save & load section data
• ⌨️ TypeScript support
• 🔒 Read-only mode
• 🎛️ Minimum size constraints
• 🔢 Maximum sections limit
• 🪝 Event hooks for clicks and hovers

Demo & Examples

Live Demo: https://react-image-section-mapper-demo.vercel.app/

Demo Repo: https://github.com/mdtanvirahamedshanto/react-image-section-mapper-demo

Installation

npm install react-image-section-mapper
# or
yarn add react-image-section-mapper
# or
pnpm add react-image-section-mapper

Basic Usage

import { ImageSectionMapper } from 'react-image-section-mapper';

function App() {
  const handleSave = (sections) => {
    console.log('Sections:', sections);
    // Save sections to your backend
  };

  return (
    <ImageSectionMapper
      imageUrl="/path/to/your/image.jpg"
      onSave={handleSave}
    />
  );
}

Advanced Usage

import { ImageSectionMapper, Section } from 'react-image-section-mapper';

function AdvancedExample() {
  // Initial sections data
  const initialSections: Section[] = [
    {
      id: '1',
      x: 100,
      y: 100,
      width: 200,
      height: 150,
      title: 'Custom Section',
      link: '/custom-link'
    }
  ];

  // Handlers
  const handleSave = async (sections: Section[]) => {
    try {
      await saveToBackend(sections);
    } catch (error) {
      console.error('Failed to save sections:', error);
    }
  };

  const handleSectionClick = (section: Section) => {
    console.log('Clicked section:', section);
  };

  const handleSectionHover = (section: Section | null) => {
    if (section) {
      console.log('Hovering section:', section);
    }
  };

  return (
    <ImageSectionMapper
      imageUrl="/path/to/your/image.jpg"
      initialSections={initialSections}
      onSave={handleSave}
      onSectionClick={handleSectionClick}
      onSectionHover={handleSectionHover}
      sectionTitlePrefix="Area"
      minSectionSize={50}
      maxSections={10}
      theme={{
        primary: 'blue',
        secondary: 'gray',
        danger: 'red',
        success: 'green'
      }}
      readOnly={false}
      controls={true}
      className="custom-mapper"
    />
  );
}

Props

Types

Section

interface Section {
  id?: string;
  x: number;
  y: number;
  width: number;
  height: number;
  title: string;
  link?: string;
}

Theme

interface Theme {
  primary: string;
  secondary: string;
  danger: string;
  success: string;
}

Styling

The component uses Tailwind CSS classes by default. You can customize the appearance by:

1. Using the theme prop to change colors
2. Providing custom classes via the className prop
3. Overriding the default styles in your CSS

/* Example custom styles */
.custom-mapper .section-title {
  font-weight: bold;
}

.custom-mapper .resize-handle:hover {
  background-color: #4a90e2;
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

Development

# Install dependencies
npm install

# Run type checking
npm run type-check

# Build the package
npm run build

# Run tests
npm test

License

MIT © Md Tanvir Ahamed Shanto

Support

If you have any questions or need help, please:

1. Check the issues for existing problems and solutions
2. Create a new issue if your problem isn't already reported
3. Contact the maintainers

Made with ❤️ by Md Tanvir Ahamed Shanto

Changelog

All notable changes to this project will be documented in this file.

[1.0.3] - 2025-02-12

Added

• Initial release of react-image-section-mapper that allows users to create interactive, resizable, and draggable sections on images.
• Useful for image annotation, mapping hot zones, or adding interactive UI elements.

Changed

• N/A

Fixed

• Button Styling

[1.0.2] - 2025-02-12

Added

• Initial release of react-image-section-mapper that allows users to create interactive, resizable, and draggable sections on images.
• Useful for image annotation, mapping hot zones, or adding interactive UI elements.

Changed

• N/A

Fixed

• Button Styling

[1.0.1] - 2025-02-12

Added

• Initial release of react-image-section-mapper that allows users to create interactive, resizable, and draggable sections on images.
• Useful for image annotation, mapping hot zones, or adding interactive UI elements.

Changed

• N/A

Fixed

• Some Styling

[1.0.0] - 2025-02-11

Added

• First public version of react-image-section-mapper on GitHub.
• Basic functionality for interactive sections on images.

[Unreleased]

Added

• N/A