react-image-area

React component to select multiple areas/regions of images.

Live Example

:books: Table of Contents

• Installation
• Usage
• Features
• Docs
• Support
• Contributing
• License

:package: Installation

npm i @bmunozg/react-image-area

Peer dependencies: React 17, 18, and 19 are all supported.

:rocket: Usage

Usage with types

import { AreaSelector, IArea } from '@bmunozg/react-image-area'

const ExampleComponent = () => {
    const [areas, setAreas] = useState<IArea[]>([]);

    const onChangeHandler = (areas: IArea[]) => {
        setAreas(areas);
    }

    return (
        <AreaSelector
            areas={areas}
            onChange={onChangeHandler}
        >
            <img src='my-image.jpg' alt='my image'/>
        </AreaSelector>
    )
}

:key: Features

• Responsive (you can use pixels or percentages).
• Touch enabled.
• Min/max area size.
• Custom area render

:notebook: Docs

• Required Props

  • areas: IArea[]

    Starting with no areas:

    // ...
    const [areas,setAreas] = useState<IArea[]>([])
    // ...
    return (
        <AreaSelector
            areas={areas}
        >
            <img src='my-image.jpg' alt='my image'/>
        </AreaSelector>
    )
    // ...
    

  • onChange: (areas: IArea[]) => void

    A callback which happens for every change on the selection area.

    // ...
    const [areas,setAreas] = useState<IArea[]>()
    // ...
    return (
        <AreaSelector
            onChange={setAreas}
        >
            <img src='my-image.jpg' alt='my image'/>
        </AreaSelector>
    )
    // ...
    

• Default Props

  • maxAreas: number

    Default: Infinity

    Set the maximum areas that can be drawn, by default there are no limit.

  • unit: 'pixel' | 'percentage'

    Default: pixel

    Set the unit you want to work with.

  • minWidth: number

    Default: 0

    Min width of the areas.

  • minHeight: number

    Default: 0

    Min height of the areas.

  • debug: boolean

    Default: false

    Display info of the current areas.

• Optional Props

  • maxWidth: number

    Max width of the areas.

  • maxHeight: number

    Max height of the areas.

  • wrapperStyle: CSSProperties

    Apply styles to the wrapper element.

    Omited Styles: touchAction | boxSizing

    wrapperStyle={{
        border: '2px solid black'
    }}
    

  • globalAreaStyle: CSSProperties

    Apply global styles to the areas.

    Omited Styles: position | touchAction | top | left | width | height | boxSizing

    globalAreaStyle={{
        border: '1.5px dashed blue',
        backgroundColor: 'lightblue',
        opacity: '0.5'
    }}
    

  • customAreaRenderer: (areaProps: IAreaRendererProps) => ReactNode

    Custom render function to display info inside the areas. Remember to add a key

    import { AreaSelector, IAreaRendererProps } from '@bmunozg/react-image-area'
    // ...
    const customRender = (areaProps: IAreaRendererProps) => {
        if (!areaProps.isChanging) {
            return (
                <div key={areaProps.areaNumber}>
                    {areaProps.areaNumber}
                </div>
            );
        }
    };
    // ...
    return (
        <AreaSelector
            {/*...*/}
            customAreaRenderer={customRender}
        >
            <img src='my-image.jpg' />
        </AreaSelector>
    );
    // ...
    

  • mediaWrapperClassName: string

    Classname to apply to the media wrapper (image passed as children).

    // ...
    return (
        <AreaSelector>
            <img src="my-image.jpg" />
        </AreaSelector>
    );
    // ...
    

    inside the component :arrow_down:

    // ...
    return (
        <div {/*wrapperStyle*/}>
            <div className={mediaWrapperClassName}>
                {/*image passed as children*/}
            </div>
            {/*...Areas*/}
        </div>
    )
    //...
    

:hammer_and_wrench: Support

Please open an issue for support.

:memo: Contributing

Please contribute using Github Flow. Create a branch, add commits, and open a pull request.

:scroll: License

MIT © ByronMunozG