react-image-section-mapper

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

Prop	Type	Default	Description
imageUrl	string	Required	URL of the image to map sections on
onSave	(sections: Section[]) => void | Promise<void>	-	Callback when sections are saved
initialSections	Section[]	[]	Initial sections to display
sectionTitlePrefix	string	'Section'	Prefix for auto-generated section titles
className	string	''	Additional CSS classes
controls	boolean	true	Show/hide control buttons
theme	Theme	defaultTheme	Custom theme colors
minSectionSize	number	20	Minimum width/height of sections
maxSections	number	-	Maximum number of sections allowed
readOnly	boolean	false	Disable editing capabilities
onSectionClick	(section: Section) => void	-	Callback when a section is clicked
onSectionHover	(section: Section | null) => void	-	Callback when a section is hovered

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:

• Using the theme prop to change colors
• Providing custom classes via the className prop
• 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.

• Fork the repository
• Create your feature branch (git checkout -b feature/AmazingFeature)
• Commit your changes (git commit -m 'Add some AmazingFeature')
• Push to the branch (git push origin feature/AmazingFeature)
• 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:

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

Made with ❤️ by Md Tanvir Ahamed Shanto