Welcome to Vanilla Breeze
This bell pulls live notifications from /go/notify/messages — the same contract documented at /docs/concepts/service-contracts/. Static articles like this one are the no-JS / no-backend fallback.
image-map
Modern responsive image map with percentage-based coordinates, rich HTML tooltips, keyboard navigation, and progressive enhancement.
Overview
The <image-map> component replaces native HTML <map>/<area> with percentage-based coordinates that scale responsively. Areas are defined as <map-area> children with rich HTML tooltip content, full keyboard navigation, and progressive enhancement.
Basic image map
<image-map> <img src="/maps/floor-plan.svg" alt="Office floor plan" /> <map-area shape="rect" coords="5 8 40 44" label="Conference Hall" href="/rooms/conference"> <strong>Conference Hall</strong> <p>Seats 120 people. AV equipment available.</p> </map-area> <map-area shape="circle" coords="62.5 32 10" label="Server Room" href="/rooms/server"> <strong>Server Room</strong> <p>24 racks, climate controlled.</p> </map-area> <map-area shape="rect" coords="60 56 95 92" label="Open Office" href="/rooms/office"> <strong>Open Office</strong> <p>80 hot-desk workstations.</p> </map-area></image-map>Markup Pattern
Place an <img> as a direct child of <image-map>. The component adopts it and overlays an SVG hit-testing layer. Each <map-area> defines a hotspot region — its inner HTML becomes the tooltip content.
Alternatively, src and alt attributes on <image-map> itself can create the image, but placing <img> as a child gives better progressive enhancement.
Coordinate System
All coordinates are percentages (0–100) of the rendered image dimensions — not pixels. Values are unitless numbers separated by spaces or commas. The SVG overlay uses viewBox="0 0 100 100" so percentage coordinates map directly to SVG units with no runtime conversion.
All shape types
<!-- Rectangle: x1 y1 x2 y2 --><map-area shape="rect" coords="5 8 40 44" label="Conference Hall">...</map-area> <!-- Circle: cx cy radius --><map-area shape="circle" coords="62.5 32 10" label="Server Room">...</map-area> <!-- Polygon: x1 y1 x2 y2 x3 y3 ... --><map-area shape="poly" coords="60 56 95 56 95 92 70 92 60 76" label="Open Office">...</map-area>| Shape | Coords format | Description |
|---|---|---|
rect |
x1 y1 x2 y2 |
Top-left and bottom-right corners |
circle |
cx cy r |
Centre point and radius (radius is % of image width) |
poly |
x1 y1 x2 y2 ... |
Series of points (minimum 3), auto-closes |
All Shapes Demo
Tooltip Content
The inner HTML of each <map-area> becomes the tooltip content. Use any HTML: headings, paragraphs, lists, images, links.
Tooltip modes
By default, tooltips show on hover (tooltip="hover"). Set tooltip="click" for click-to-toggle, which is better for tooltips with interactive content like links. Set tooltip="none" to disable tooltips entirely.
Click-mode tooltip
<map-area shape="rect" coords="5 8 40 44" label="Conference Hall" tooltip="click"> <strong>Conference Hall</strong> <p>Click to see details. Click again to dismiss.</p> <p><a href="/book">Book this room</a></p></map-area>CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--map-area-color |
oklch(60% 0.2 250 / 0.08) |
Default area fill (subtle hint) |
--map-area-color-hover |
oklch(60% 0.2 250 / 0.35) |
Hover/focus area fill |
--map-area-stroke |
oklch(60% 0.2 250 / 0.3) |
Default area outline stroke |
--map-tooltip-bg |
oklch(15% 0 0 / 0.92) |
Tooltip background |
--map-tooltip-color |
white |
Tooltip text colour |
--map-tooltip-radius |
0.5rem |
Tooltip border radius |
--map-tooltip-max-width |
20rem |
Tooltip maximum width |
Custom styling
image-map { --map-area-color: oklch(55% 0.2 140 / 0.3); --map-area-color-hover: oklch(55% 0.2 140 / 0.6); --map-tooltip-bg: oklch(20% 0.02 220 / 0.95); --map-tooltip-radius: 0.75rem; --map-tooltip-max-width: 24rem;}Attributes
<image-map>
| Attribute | Type | Description |
|---|---|---|
src |
string | Image URL (fallback if no child <img>) |
alt |
string | Image alt text (fallback if no child <img>) |
aria-label |
string | Accessible label for the map group (defaults to img alt) |
<map-area>
| Attribute | Type | Required | Description |
|---|---|---|---|
shape |
string | Yes | rect, circle, or poly |
coords |
string | Yes | Space or comma-separated percentage values (0–100) |
label |
string | Yes | Accessible name for the hotspot |
href |
string | No | Navigation target. Creates an <a> focus anchor |
target |
string | No | Link target (_blank, etc.) |
tooltip |
string | No | hover (default), click, or none |
disabled |
boolean | No | Suppresses interaction and tooltip |
Events
| Event | Detail | Description |
|---|---|---|
image-map:area-enter |
{ area } |
Pointer or focus entered an area |
image-map:area-leave |
{ area } |
Pointer or focus left an area |
image-map:area-activate |
{ area } |
Area clicked or Enter pressed |
Event handling
const map = document.querySelector('image-map'); map.addEventListener('image-map:area-enter', (e) => { console.log('Entered:', e.detail.area.label);}); map.addEventListener('image-map:area-activate', (e) => { console.log('Activated:', e.detail.area.label);});Keyboard Navigation
| Key | Action |
|---|---|
| Tab | Move focus between area anchors |
| ↓ / → | Focus next area |
| ↑ / ← | Focus previous area |
| Enter / Space | Activate area (follow link or dispatch event) |
| Escape | Dismiss tooltip |
Accessibility
Each <map-area> generates a focusable anchor element (<a> when href is set, <button> otherwise) with aria-label matching the area’s label attribute. The SVG overlay is aria-hidden — it handles only pointer hit-testing. The tooltip uses role="tooltip" and aria-live="polite" for screen reader announcements.
The host element uses role="group" with an aria-label derived from the image alt text.
Progressive Enhancement
Without JavaScript
<!-- Without JS, image renders normally --><!-- map-area elements display as a labeled list --> <image-map> <img src="plan.svg" alt="Floor plan" /> <map-area shape="rect" coords="..." label="Room A" href="/a"> tooltip content (hidden without JS) </map-area></image-map> <!-- Renders as: [image] • Room A-->Touch Behaviour
On touch devices with tooltip="hover", a two-tap pattern is used: the first tap shows the tooltip, the second tap navigates (if href is set). For tooltip="click", tapping toggles the tooltip on/off. Press Escape or tap elsewhere to dismiss.
Related
- tool-tip — General-purpose tooltip component
- geo-map — Interactive geographic maps
- compare-surface — Before/after image comparison
- map — Native HTML image map (pixel-based)
- area — Native HTML area element