Build map-based and location-aware features targeting iOS 17+ with SwiftUI
MapKit and modern CoreLocation async APIs. Use Map with MapContentBuilder
for views, CLLocationUpdate.liveUpdates() for streaming location, and
CLMonitor for geofencing.
Read references/mapkit-patterns.md when you need full map setup, search, routes, Look Around, snapshots, or iOS 26 place APIs. Read references/mapkit-corelocation-patterns.md when the task involves location update lifecycle, geofencing, background location, testing, or privacy keys.
Contents
- Workflow
- Route by Task
- Core Decisions
- Common Mistakes
- Review Checklist
- References
Workflow
- Define the exact map/location capability and request only the authorization it needs.
- Choose SwiftUI Map or UIKit hosting, then establish camera ownership, selection, annotations, and overlay identity.
- Keep search, geocoding, directions, and live-location tasks cancellable and scoped to the current query/session.
- Handle denied/restricted/reduced-accuracy states and avoid treating coordinates as always available.
- Verify empty results, movement, camera changes, route failures, localization, offline/network transitions, and background rules.
Route by Task
- Read core implementation details for SwiftUI maps, camera, annotations, overlays, live updates, authorization, geocoding, search, and directions.
- Read MapKit patterns for clustering, Look Around, snapshots, complex routes, and full map setup.
- Read Core Location patterns for
CLLocationUpdate, monitoring, service sessions, background behavior, and testing.
Core Decisions
- Do not infer authorization from API availability or a non-nil cached location.
- Use stable identities for annotations and overlays.
- Debounce and cancel search/geocoding work when input changes.
- Treat size, viewport, and user interaction as live state rather than fixed screen assumptions.
Common Mistakes
DON'T: Request always authorization upfront.
DO: Start with when-in-use authorization. On iOS 18+, hold a CLServiceSession
for the feature lifetime; request .always only for background features that
need system relaunch after termination.
DON'T: Use CLLocationManagerDelegate for simple location fetches on iOS 17+.
DO: Use CLLocationUpdate.liveUpdates() async stream for cleaner, more concise code.
DON'T: Ignore CLLocationUpdate diagnostics such as denied, globally denied, or unavailable location.
DO: Stop or degrade the feature, show recovery UI such as Settings guidance, and keep search/manual flows usable.
DON'T: Let liveUpdates() run from an unowned task after the map/view is gone.
DO: Store the Task, cancel it when the feature stops, and filter invalid, inaccurate, stale, or impossible movement fixes.
DON'T: Force-unwrap CLPlacemark properties — they are all optional.
DO: Use nil-coalescing: placemark.locality ?? "Unknown".
DON'T: Fire MKLocalSearchCompleter queries on every keystroke.
DO: Debounce with .task(id: searchText) + Task.sleep(for: .milliseconds(300)).
DON'T: Silently fail when location authorization is denied.
DO: Detect .denied status and show an alert with a Settings deep link.
DON'T: Assume geocoding always succeeds — handle empty results and network errors.
Review Checklist
- Info.plist has
NSLocationWhenInUseUsageDescriptionwith specific reason - Authorization denial handled with Settings deep link
-
CLLocationUpdatetask cancelled when not needed (battery) - Location accuracy appropriate for the use case
- Map annotations use
Identifiabledata with stable IDs - Geocoding errors handled (network failure, no results)
- Search completer input debounced
-
CLMonitorlimited to 20 conditions, instance kept alive - Background location uses
CLBackgroundActivitySession - Map tested with VoiceOver
- Map annotation view models and location UI updates are
@MainActor-isolated
References
- references/mapkit-patterns.md — Map setup, annotations, search, routes, clustering, Look Around, snapshots.
- references/mapkit-corelocation-patterns.md — CLLocationUpdate, CLMonitor, CLServiceSession, background location, testing.
- Core implementation details -- setup, API wiring, and focused implementation recipes moved out of the entrypoint.