@a11y-ngx/responsive-image-maps

Responsive Image Maps

A responsive image map Angular directive that updates the areas' coordinates according to the image size.

It will manage all shapes (rect, circle and poly).

This library was generated with Angular CLI version 12.2.0.

Index

• Installation
• Use
  • The Map Directive
    • The Map public Properties, Getters and Methods
    • The MapSize Type
  • The Area Directive
    • The Area public Properties, Getters and Methods
    • The AreaSize Type
• Working Example

Installation

1. Install npm package:

   npm install @a11y-ngx/responsive-image-maps --save

2. Import A11yResponsiveImageMapsModule into your module or standalone component:

   import { A11yResponsiveImageMapsModule } from '@a11y-ngx/responsive-image-maps';
   
   @NgModule({
       declarations: [...],
       imports: [
           ...
           A11yResponsiveImageMapsModule,
       ],
   })
   export class AppModule { }

Use

Add an image with a map in your template.

The Map Directive

• The Map directive will pick any <map> tag with [name] attribute in it and search for the <img> with [usemap] matching that name.
• When the image has been loaded for the first time, it will:
  • Update loaded with true.
  • Emit sizeChanged.
• When the main <img> resizes, all <area> elements will update their coordinates based on the new image size.
• The directive can be accessed using a template variable through the exported name of responsiveImageMap.
• The directive will auto update sizes when the page resizes (using Window Resize Service).
• If the image changes its size:
  • Through window resize, (sizeChanged) output will emit the new MapSize.
  • Pogrammatically, the sizes (image and areas) can be manually updated using the update() method from the exported directive.
• The HTML <map> element can be reached through the nativeElement property.
• The HTML <img> element can be reached through the imageElement property.

Map Directive public Properties, Getters and Methods

Property	Type	Returns	Description
loaded	BehaviorSubject	boolean	Will return true when the image has been loaded
sizeChanged	EventEmitter	MapSize	Will emit the new image's size & position when page resize and it changes the width and height values
areas	QueryList	ResponsiveImageAreaDirective	To access all <area> children directives
scaleFactor	get	{ width: number, height: number }	The scale factor from the image's original full size and the resized size
imageSize	MapSize	object	To access all the values (size & position) from the main image
nativeElement	get	HTMLMapElement	To access the HTML <map> element
imageElement	get	HTMLImageElement	To access the HTML <img> element that the <map> is attached to
update()	method	void	Will update the image new values and all the <area>'s new coordinates accordingly

The MapSize Type

Property	Type	Description
top	number	The image DOMRect's top value
left	number	The image DOMRect's left value
width	number	The image DOMRect's width value
height	number	The image DOMRect's height value
fullWidth	number	The image's original full width size (resized or not)
fullHeight	number	The image's original full height size (resized or not)

The Area Directive

• The Area directive will pick any <area> tag with [shape] and [coords] attributes.
• This directive will manage the area size (either relative to the image or to the viewport).
• Each directive can be accessed:
  • Using a template variable through the exported name of responsiveImageArea.
  • From the Map directive through the areas property, which will return a QueryList<ResponsiveImageAreaDirective>.
• The HTML <area> element can be reached through the nativeElement property.

Area Directive public Properties, Getters and Methods

Property	Type	Returns	Description
areaSize	AreaSize	object	To access all the values (size & position) from the area (relative to the image)
nativeElement	get	HTMLAreaElement	To access the HTML <area> element
getBoundingClientRect()	method	DOMRect	To get the calculated position of the <area> element (relative to the viewport)
updateCoords()	method	void	Will update the [coords] attribute based on the image size. (NOTE: there's no need to trigger this manually, the map directive will update when needed)

The AreaSize Type

Property	Type	Description
top	number	The area's (relative to image) top value
left	number	The area's (relative to image) left value
width	number	The area's width value
height	number	The area's height value

Working Example

TypeScript

import { ResponsiveImageMapDirective, MapSize, AreaSize } from '@a11y-ngx/responsive-image-maps';

@Component({ ... })
export class MyComponent {
    @ViewChild('imageMap') imageMap: ResponsiveImageMapDirective;

    updateOtherElements(newSize: MapSize): void {
        const width = newSize.width;
        const height = newSize.height;
        ...

        this.imageMap.areas.forEach(area => {
            const areaElement = area.nativeElement;
            const areaSize: AreaSize = area.areaSize;
            ...
        });
    }

    updateMapSizes(): void {
        this.imageMap.update();
    }
}

HTML

<img src="https://www.w3schools.com/html/workplace.jpg" alt="Workplace" usemap="#workmap">

<map name="workmap" #imageMap="responsiveImageMap" (sizeChanged)="updateOtherElements($event)">
    <area shape="rect" coords="34,44,270,350" alt="Computer" href="...">
    <area shape="rect" coords="290,172,333,250" alt="Phone" href="...">
    <area shape="circle" coords="337,300,44" alt="Coffee" href="...">
</map>