UX Patterns Guide
UI + UX Data Display And Exploration established

Map view

Provide a Map view with coordinate-anchored objects, pan and zoom, marker selection, popups or details, clustering, layers, geolocation recovery, viewport-aware counts, route or radius context, legends, and a synchronized non-map fallback.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • Users choose or inspect objects by where they are, how near they are, or what area they fall inside.
  • Density, clusters, routes, regions, service areas, or nearby alternatives matter to the task.
  • The product can keep map state, selected detail, result list, and location source synchronized.
  • A non-map fallback can support users who cannot or do not want to use visual map interaction.

Avoid when

  • Location is only a label or decorative backdrop.
  • Users primarily compare structured fields or bulk-edit records.
  • Users primarily manage time, duration, recurrence, or availability.
  • The implementation cannot provide clustering, fallback results, permission recovery, or accessible controls.
  • Approximate or stale coordinates would mislead users without clear disclosure.

Problem it prevents

Users need to make decisions from geographic position, distance, route, density, region, or coverage, but list, table, and calendar surfaces flatten location into text and hide spatial relationships.

Pattern anatomy

What a strong implementation has to make clear

User need

Locations, assets, incidents, events, service areas, deliveries, rooms, or routes are meaningful because of where they are.

Pattern promise

Provide a Map view with coordinate-anchored objects, pan and zoom, marker selection, popups or details, clustering, layers, geolocation recovery, viewport-aware counts, route or radius context, legends, and a synchronized non-map fallback.

Required state

Default map state with visible viewport, zoom level or distance context, markers, layer state, result count, and synchronized fallback list.

Recovery path

Markers overlap and users cannot tell how many results are hidden.

Access contract

Expose the map name, current area, result count, active filters, layers, selected place, and location permission state as text.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A clinic finder map shows visible bounds, zoom level, selected clinic marker, appointment availability markers, a transit layer toggle, cluster counts, distance chips, and a synchronized results list.
  • An operations incident map shows sensor markers, outage polygons, a legend, selected incident popup, service-radius overlay, stale-data badge, and keyboard-accessible place list.
  • A dispatcher pans to the west district, the result count and list update to the current bounds, a cluster expands at closer zoom, and the selected incident popup remains tied to the marker.
  • A traveler denies location permission, enters an address instead, sees nearby stations sorted by distance, toggles bike-lane and transit layers, and previews a route without losing the selected station.
Weak implementation

Vague, hidden, hard to recover from

  • A decorative map background contains unlabeled pins with no coordinate meaning, no current region, no selected marker, no legend, and no list fallback.
  • A store locator uses a full map but every pin overlaps, cluster counts are missing, distance is not shown, and the popup floats away from the selected location.
  • A user filters to open locations but the map markers update while the list still shows closed locations, causing the wrong branch to be selected.
  • A location permission prompt is rejected and the entire locator becomes unusable even though manual search or a saved address exists.
UI guidance
  • Render a real spatial viewport with visible map region, zoom state, scale or distance context, markers or shapes anchored to coordinates, selected-place detail, cluster counts, visible layer/filter controls, and a fallback list or table for the same results.
  • Show marker states, selected marker, popup or side-detail position, cluster expansion, geolocation permission state, route or radius overlays, legends, empty-region state, and loading or stale-tile states without depending on color or pointer hover alone.
UX guidance
  • Use Map view when the user's decision depends on where objects are, how far apart they are, what falls inside the current area, which route or coverage applies, or how dense nearby points are.
  • Keep spatial interaction honest: panning, zooming, filtering, clustering, geolocation, route preview, and popup selection must update counts, bounds, fallback list, distance context, and focus in ways that preserve the selected place.
Implementation contract

What the implementation must handle

States

  • Default map state with visible viewport, zoom level or distance context, markers, layer state, result count, and synchronized fallback list.
  • Marker selected, marker focused, popup open, popup dismissed, side detail open, and selected item in fallback list.
  • Clustered markers, expanded cluster, dense overlap, empty region, filtered region, hidden layer, and hidden-result count states.
  • Panning, zooming, search-this-area, fit-to-results, route preview, radius selection, and layer toggle states.

Interaction

  • Markers, shapes, routes, clusters, and overlays represent explicit coordinates, features, or geographic areas, not decorative positions.
  • Panning, zooming, filtering, layer toggling, and search-this-area update visible markers, counts, selected detail, and fallback list from the same result set.
  • Selecting a marker opens a popup or detail that names the place, explains relevant distance or status, and provides a keyboard path back to the marker and fallback list.
  • Clusters expose count and category composition when useful, and users can expand, zoom, or inspect contained items without losing map context.

Accessibility

  • Expose the map name, current area, result count, active filters, layers, selected place, and location permission state as text.
  • Give markers or fallback list rows accessible names with place name, category, status, distance, and selected state.
  • Provide keyboard-operable controls for search, zoom, pan alternatives, fit-to-results, layer toggles, cluster expansion, marker selection, popup close, and list fallback.
  • Keep marker popup focus contained only when needed, return focus to the selected marker or list row, and do not trap focus in the map canvas.

Review

  • What spatial decision does the map make easier than a list, table, calendar, or chart?
  • Can users tell the current area, zoom, layer state, result count, and selected marker?
  • Do markers, clusters, popups, fallback list, filters, and bounds update from the same data?
  • What happens when markers overlap, map tiles fail, location permission is denied, or the selected marker moves offscreen?
Interactive lab

Inspect the states before you copy the pattern

Inspect places in spatial context

Pan the viewport, zoom to expand a cluster, select a marker, toggle layers, deny and recover from location permission, fit results, open route preview, switch list fallback, and compare decorative-pins, no-cluster, no-legend, permission-dead-end, stale-bounds, hover-only, and wrong-distance failures.

Map view
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

Default map state with visible viewport, zoom level or distance context, markers, layer state, result count, and synchronized fallback list.

Keyboard / Access

Tab reaches search, result count, layer controls, zoom controls, fit-to-results, selected place detail, fallback list, and primary place actions.

Avoid Generating

Using a map as decoration when the positions do not affect the task.
Evidence trail

Source-backed claims behind this guidance

Mapbox GL JS: Markers

Mapbox - checked

Mapbox documents markers as coordinate-positioned interactive elements for specific locations.

Leaflet: Quick Start Guide

Leaflet - checked

Leaflet documents mobile-friendly interactive maps with markers, popups, geometry, and event handling.

Full agent/debug reference

Problem Context

  • Locations, assets, incidents, events, service areas, deliveries, rooms, or routes are meaningful because of where they are.
  • Users may need to pan, zoom, search within bounds, inspect clusters, choose a nearby item, compare distance, or understand coverage.
  • Maps often combine basemap tiles, vector layers, markers, routes, polygons, popups, clustering, filters, and browser geolocation.
  • Location permission, stale tiles, dense markers, hidden layers, offscreen popups, and unsynchronized fallback lists can make a map misleading.
  • Map view must remain usable for keyboard users, low-vision users, users who deny location, and users who need a structured list instead of visual geography.

Selection Rules

  • Choose Map view when spatial relationship, proximity, coverage, route, region, or real-world placement changes the user's decision.
  • Use list view when the main task is scanning object summaries and location can be represented as text or a distance sort.
  • Use table when users need aligned field comparison, bulk review, or export of records.
  • Use calendar view when time placement, duration, availability, or recurrence matters more than geography.
  • Use data visualization when the task is aggregate trend, distribution, or metric analysis rather than choosing place-level objects.
  • Use search results when ranked matching is primary and map position is secondary.
  • Cluster dense markers and disclose cluster counts when markers overlap or density makes individual selection unreliable.
  • Show the current area, active layers, filters, location source, selected marker, and result count so the map's scope is not ambiguous.
  • Provide a fallback list, table, or accessible result summary that stays synchronized with the map bounds and filters.
  • Avoid Map view when coordinates are decorative, approximate without disclosure, or unrelated to the user's decision.
  • Avoid Map view as the only control when geolocation permission or map tile loading can fail.

Required States

  • Default map state with visible viewport, zoom level or distance context, markers, layer state, result count, and synchronized fallback list.
  • Marker selected, marker focused, popup open, popup dismissed, side detail open, and selected item in fallback list.
  • Clustered markers, expanded cluster, dense overlap, empty region, filtered region, hidden layer, and hidden-result count states.
  • Panning, zooming, search-this-area, fit-to-results, route preview, radius selection, and layer toggle states.
  • Geolocation requested, allowed, denied, unavailable, manual-location fallback, and approximate-location disclosure states.
  • Loading tiles, failed tiles, stale map data, slow network, offline fallback, and attribution visible states.
  • Keyboard marker navigation, list fallback navigation, popup focus return, and non-pointer route or selection states.
  • Responsive state where map controls, selected detail, bounds count, and fallback list remain reachable on mobile.

Interaction Contract

  • Markers, shapes, routes, clusters, and overlays represent explicit coordinates, features, or geographic areas, not decorative positions.
  • Panning, zooming, filtering, layer toggling, and search-this-area update visible markers, counts, selected detail, and fallback list from the same result set.
  • Selecting a marker opens a popup or detail that names the place, explains relevant distance or status, and provides a keyboard path back to the marker and fallback list.
  • Clusters expose count and category composition when useful, and users can expand, zoom, or inspect contained items without losing map context.
  • Geolocation is optional unless the task truly requires it; denied or unavailable location provides manual search, saved location, current map area, or list fallback.
  • Legends and text labels explain marker color, shape, heat, route, polygon, radius, and layer meaning.
  • Distances, routes, travel times, and service areas state origin, unit, mode, approximation, and stale-data status when those affect the decision.
  • Keyboard and assistive-technology users can reach layer controls, search, result list, selected place details, and map movement alternatives without pointer-only gestures.

Implementation Checklist

  • Define feature schema: id, name, coordinate, geometry type, category, status, distance, availability, popup fields, route metadata, layer, timestamp, and permissions.
  • Define viewport model: center, zoom, bounds, selected feature, active filters, active layers, result count, cluster state, and fallback-list ordering.
  • Implement marker selection, popup or side detail, fit-to-results, search-this-area, cluster expansion, layer toggles, radius or route preview, and manual location fallback.
  • Keep map markers, cluster counts, fallback list, search results, and selected detail synchronized after pan, zoom, filter, layer, and geolocation changes.
  • Model empty region, dense cluster, denied location, unavailable geolocation, stale data, failed tiles, hidden layer, offscreen popup, and mobile stacked layouts.
  • Show attribution, legends, scale or distance context, location source, and result scope near the map.
  • Test keyboard access, popup focus return, marker labels, high marker density, long place names, small screens, slow tiles, and denied browser permissions.
  • Use a proven map SDK or service for projection, panning, tile loading, clustering, geolocation, and geometry math in production rather than inventing spatial math.

Common Generated-UI Mistakes

  • Using a map as decoration when the positions do not affect the task.
  • Showing markers without labels, selected state, popup detail, count, or fallback list.
  • Letting dense markers overlap without clustering or zoom guidance.
  • Treating geolocation denial as a dead end.
  • Changing map filters without updating list results and result counts.
  • Showing route, distance, radius, or service area without units, origin, mode, or approximation.
  • Hiding layer meaning behind color-only markers with no legend.
  • Making panning, zooming, popup opening, or marker selection pointer-only.

Critique Questions

  • What spatial decision does the map make easier than a list, table, calendar, or chart?
  • Can users tell the current area, zoom, layer state, result count, and selected marker?
  • Do markers, clusters, popups, fallback list, filters, and bounds update from the same data?
  • What happens when markers overlap, map tiles fail, location permission is denied, or the selected marker moves offscreen?
  • Can keyboard and assistive-technology users inspect places and complete the task without dragging or hovering on the map?
  • Would a list view, table, calendar view, data visualization, or search result list better fit the task?
Accessibility
  • Expose the map name, current area, result count, active filters, layers, selected place, and location permission state as text.
  • Give markers or fallback list rows accessible names with place name, category, status, distance, and selected state.
  • Provide keyboard-operable controls for search, zoom, pan alternatives, fit-to-results, layer toggles, cluster expansion, marker selection, popup close, and list fallback.
  • Keep marker popup focus contained only when needed, return focus to the selected marker or list row, and do not trap focus in the map canvas.
  • Do not rely only on color for marker category, availability, route, radius, selection, cluster density, or stale data.
  • Announce changes to result count, selected place, geolocation denial, active layers, search-this-area updates, and failed map tiles in text or status regions.
  • Maintain usable target sizes and avoid controls that overlap attribution, selected detail, or mobile browser safe areas.
Keyboard Behavior
  • Tab reaches search, result count, layer controls, zoom controls, fit-to-results, selected place detail, fallback list, and primary place actions.
  • Enter or Space selects markers in the fallback list, opens and closes place detail, toggles layers, expands clusters, and previews routes.
  • Arrow-key map panning may be implemented, but non-pointer controls or fallback list navigation must still make the task possible.
  • Escape closes popups, route previews, layer menus, and geolocation prompts and returns focus to the invoking control.
  • After pan, zoom, filter, search-this-area, or cluster expansion, focus remains near the triggering control or moves to an announced result summary.
  • When geolocation fails or is denied, focus moves to manual location entry or a clear fallback action.
Variants
  • Store locator map
  • Asset tracking map
  • Incident map
  • Delivery route map
  • Property search map
  • Transit stop map
  • Indoor venue map
  • Coverage area map
  • Service radius map
  • Heatmap with point details
  • Clustered marker map
  • Map with synchronized result list

Verification

Last verified: