dpearson2699/swift-ios-skills / skills/mapkit
mapkit
VerifiedImplement, review, or improve maps and location features in iOS/macOS apps using MapKit and CoreLocation. Use when working with Map views, annotations, markers, polylines, user location tracking, geocoding, reverse geocoding, search/autocomplete, directions and routes, geofencing, region monitoring, CLLocationUpdate async streams, or location authorization flows. Also use when working with maps, coordinates, addresses, places, directions, distance calculations, or location-based features in Swift apps.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.0 KB |
| evals/evals.json | config | 4.4 KB |
| references/mapkit-corelocation-patterns.md | markdown | 23.7 KB |
| references/mapkit-patterns.md | markdown | 20.5 KB |
references/mapkit-patterns.md
View on GitHub# MapKit Patterns Reference
Extended patterns for MapKit on iOS 17+ with SwiftUI. Import `MapKit` and
`SwiftUI` in every file that uses these APIs.
```swift
import MapKit
import SwiftUI
```
---
## Contents
- [Complete Map View Setup](#complete-map-view-setup)
- [Custom Annotation Views](#custom-annotation-views)
- [Camera Control (MapCameraPosition)](#camera-control-mapcameraposition)
- [Map Selection Handling](#map-selection-handling)
- [Search with Autocomplete](#search-with-autocomplete)
- [Route Display](#route-display)
- [Look Around Preview](#look-around-preview)
- [Map Snapshots (MKMapSnapshotter)](#map-snapshots-mkmapsnapshotter)
- [Clustering Annotations](#clustering-annotations)
- [MapKit with MKMapItem Utilities](#mapkit-with-mkmapitem-utilities)
- [iOS 26 New APIs](#ios-26-new-apis)
- [User Location Display](#user-location-display)
- [Map in a List or ScrollView](#map-in-a-list-or-scrollview)
- [Coordinate Utilities](#coordinate-utilities)
- [Accessibility](#accessibility)
- [References](#references)
## Complete Map View Setup
A production-ready map view with markers, user location, and controls.
```swift
struct StoreLocatorMap: View {
let stores: [Store]
@State private var position: MapCameraPosition = .automatic
@State private var selectedStore: Store?
var body: some View {
Map(position: $position, selection: $selectedStore) {
UserAnnotation()
ForEach(stores) { store in
Marker(store.name, systemImage: "storefront",
coordinate: store.coordinate)
.tint(store.isOpen ? .green : .gray)
.tag(store)
}
}
.mapStyle(.standard(pointsOfInterest: .excludingAll))
.mapControls {
MapUserLocationButton()
MapCompass()
MapScaleView()
MapPitchToggle()
}
.safeAreaInset(edge: .bottom) {
if let store = selectedStore {
StoreDetailCard(store: store)
.padding()
}
}
}
}
```
Conform the data model to `Hashable` for use with map selection:
```swift
struct Store: Identifiable, Hashable {
let id: UUID
let name: String
let coordinate: CLLocationCoordinate2D
let isOpen: Bool
static func == (lhs: Store, rhs: Store) -> Bool { lhs.id == rhs.id }
func hash(into hasher: inout Hasher) { hasher.combine(id) }
}
```
---
## Custom Annotation Views
Use `Annotation` for fully custom SwiftUI content at a coordinate. Prefer
`Marker` for standard pins because it provides the platform marker appearance
and a title that VoiceOver can announce.
```swift
Map {
ForEach(friends) { friend in
Annotation(friend.name, coordinate: friend.coordinate, anchor: .bottom) {
VStack(spacing: 0) {
AsyncImage(url: friend.avatarURL) { image in
image.resizable().scaledToFill()
} placeholder: {
Color.gray
}
.frame(width: 40, height: 40)
.clipShape(.circle)
.overlay(Circle().stroke(.white, lineWidth: 2))
Image(systemName: "triangle.fill")
.font(.caption2)
.foregroundStyle(.white)
.rotationEffect(.degrees(180))
.offset(y: -3)
}
}
}
}
```
### Annotation with anchorOffset for callout-style layout
```swift
Annotation(place.name, coordinate: place.coordinate, anchor: .bottom) {
VStack(spacing: 2) {
Text(place.name)
.font(.caption)
.fontWeight(.semibold)
.padding(.horizontal)
.padding(.vertical)
.background(.ultraThinMaterial, in: .capsule)
Image(systemName: "mappin.circle.fill")
.font(.title)
.foregroundStyle(.red)
}
}
```
---
## Camera Control (MapCameraPosition)
### Animate camera changes
Wrap position updates in `withAnimation` for smooth transitions:
```swift
func flyTo(_ coordinate: CLLocationCoordinate2D) {
withAnimation(.easeInOut(duration: 1.0)) {
position = .camera(
MapCamera(centerCoordinate: coordinate, distance: 2000,
heading: 0, pitch: 45)
)
}
}
```
### Frame multiple annotations
```swift
func frameAllStores() {
withAnimation {
position = .automatic // Frames all map content
}
}
// Or frame a specific rect
func frameRegion(_ region: MKCoordinateRegion) {
withAnimation {
position = .region(region)
}
}
```
### Read current camera position
Use `onMapCameraChange` to observe what the user is looking at:
```swift
@State private var visibleRegion: MKCoordinateRegion?
Map(position: $position) { ... }
.onMapCameraChange(frequency: .onEnd) { context in
visibleRegion = context.region
}
```
`frequency: .onEnd` fires after the user finishes scrolling. Use
`.continuous` only when you need live tracking (costs more CPU).
---
## Map Selection Handling
### Select markers by MKMapItem
Use `MKMapItem` as the selection type when you want to look up place details:
```swift
@State private var selectedItem: MKMapItem?
Map(selection: $selectedItem) {
ForEach(searchResults) { result in
Marker(item: result)
}
}
.onChange(of: selectedItem) { _, newItem in
guard let item = newItem else { return }
Task { await fetchLookAround(for: item) }
}
```
### Select by custom Identifiable tag
```swift
@State private var selectedPlaceID: Place.ID?
Map(selection: $selectedPlaceID) {
ForEach(places) { place in
Marker(place.name, coordinate: place.coordinate)
.tag(place.id)
}
}
```
---
## Search with Autocomplete
Full pattern: completer feeds suggestions, selecting a suggestion triggers a
full search that returns `MKMapItem` results.
```swift
@Observable
final class MapSearchService: NSObject, MKLocalSearchCompleterDelegate {
var completions: [MKLocalSearchCompletion] = []
var searchResults: [MKMapItem] = []
var queryFragment: String = "" {
didSet { completer.queryFragment = queryFragment }
}
private let completer: MKLocalSearchCompleter
override init() {
completer = MKLocalSearchCompleter()
super.init()
completer.delegate = self
completer.resultTypes = [.address, .pointOfInterest]
}
// Restrict suggestions to the visible map region
func updateRegion(_ region: MKCoordinateRegion) {
completer.region = region
}
func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) {
completions = completer.results
}
func completer(_ completer: MKLocalSearchCompleter, didFailWithError error: Error) {
completions = []
}
func select(_ completion: MKLocalSearchCompletion) async {
let request = MKLocalSearch.Request(completion: completion)
request.resultTypes = [.pointOfInterest, .address]
do {
let response = try await MKLocalSearch(request: request).start()
searchResults = response.mapItems
} catch {
searchResults = []
}
}
}
```
### Search View Integration
```swift
struct MapSearchView: View {
@State private var searchService = MapSearchService()
@State private var searchText = ""
@State private var position: MapCameraPosition = .automatic
var body: some View {
Map(position: $position) {
ForEach(searchService.searchResults, id: \.self) { item in
Marker(item: item)
}
}
.searchable(text: $searchText, prompt: "Search places")
.searchSuggestions {
ForEach(searchService.completions, id: \.self) { completion in
Button {
Task { await searchService.select(completion) }
} label: {
VStack(alignment: .leading) {
Text(completion.title)
Text(completion.subtitle)
.font(.caption)
.foregroundStyle(.secondary)
}
}
}
}
.task(id: searchText) {
try? await Task.sleep(for: .milliseconds(300))
guard !Task.isCancelled else { return }
searchService.queryFragment = searchText
}
.onMapCameraChange(frequency: .onEnd) { context in
searchService.updateRegion(context.region)
}
}
}
```
---
## Route Display
Calculate directions and draw the route polyline on the map.
```swift
struct DirectionsMapView: View {
let source: MKMapItem
let destination: MKMapItem
@State private var route: MKRoute?
@State private var position: MapCameraPosition = .automatic
@State private var travelTime: String = ""
var body: some View {
Map(position: $position) {
if let route {
MapPolyline(route.polyline)
.stroke(.blue, lineWidth: 6)
}
Marker(item: source)
.tint(.green)
Marker(item: destination)
.tint(.red)
}
.overlay(alignment: .top) {
if !travelTime.isEmpty {
Text(travelTime)
.font(.caption)
.padding()
.background(.ultraThinMaterial, in: .capsule)
.padding(.top)
}
}
.task { await calculateRoute() }
}
private func calculateRoute() async {
let request = MKDirections.Request()
request.source = source
request.destination = destination
request.transportType = .automobile
do {
let response = try await MKDirections(request: request).calculate()
route = response.routes.first
if let route {
let formatter = DateComponentsFormatter()
formatter.unitsStyle = .abbreviated
formatter.allowedUnits = [.hour, .minute]
travelTime = formatter.string(from: route.expectedTravelTime) ?? ""
withAnimation {
position = .rect(route.polyline.boundingMapRect)
}
}
} catch {
print("Directions error: \(error.localizedDescription)")
}
}
}
```
### Multiple Route Options
```swift
request.requestsAlternateRoutes = true
let response = try await MKDirections(request: request).calculate()
// response.routes contains multiple route options
// Display all routes, highlight the selected one:
ForEach(Array(response.routes.enumerated()), id: \.offset) { index, route in
MapPolyline(route.polyline)
.stroke(index == 0 ? .blue : .gray.opacity(0.5), lineWidth: index == 0 ? 6 : 3)
}
```
---
## Look Around Preview
Show Apple's street-level imagery for a selected location. Availability
depends on region coverage.
```swift
struct LookAroundView: View {
let mapItem: MKMapItem
@State private var scene: MKLookAroundScene?
var body: some View {
Group {
if let scene {
LookAroundPreview(scene: .constant(scene))
.frame(height: 200)
.clipShape(.rect(cornerRadius: 12))
} else {
ContentUnavailableView("No Look Around",
systemImage: "eye.slash",
description: Text("Look Around is not available here."))
}
}
.task(id: mapItem) {
scene = nil
let request = MKLookAroundSceneRequest(mapItem: mapItem)
scene = try? await request.scene
}
}
}
```
### Look Around overlay on a Map
```swift
Map(selection: $selectedItem) { ... }
.overlay(alignment: .bottomTrailing) {
if lookAroundScene != nil {
LookAroundPreview(scene: $lookAroundScene)
.frame(width: 200, height: 130)
.clipShape(.rect(cornerRadius: 10))
.padding()
}
}
.onChange(of: selectedItem) { _, newItem in
guard let item = newItem else {
lookAroundScene = nil
return
}
Task {
let request = MKLookAroundSceneRequest(mapItem: item)
lookAroundScene = try? await request.scene
}
}
```
---
## Map Snapshots (MKMapSnapshotter)
Generate a static image of a map region. Useful for share sheets, widgets,
notifications, or thumbnails.
```swift
func generateMapSnapshot(center: CLLocationCoordinate2D,
size: CGSize = CGSize(width: 300, height: 200)) async throws -> UIImage {
let options = MKMapSnapshotter.Options()
options.region = MKCoordinateRegion(
center: center,
span: MKCoordinateSpan(latitudeDelta: 0.01, longitudeDelta: 0.01)
)
options.size = size
options.mapType = .standard
options.showsBuildings = true
let snapshotter = MKMapSnapshotter(options: options)
let snapshot = try await snapshotter.start()
// Draw a pin at the center
let image = UIGraphicsImageRenderer(size: size).image { context in
snapshot.image.draw(at: .zero)
let point = snapshot.point(for: center)
let pin = UIImage(systemName: "mappin.circle.fill")?
.withTintColor(.red, renderingMode: .alwaysOriginal)
pin?.draw(at: CGPoint(x: point.x - 15, y: point.y - 30),
blendMode: .normal, alpha: 1.0)
}
return image
}
```
---
## Dense Annotations and Clustering
For dense SwiftUI maps, hide titles at low zoom or reduce visible items based
on the current camera region. Use `MKMapView` when you need explicit cluster
configuration.
```swift
Map {
ForEach(allStores) { store in
Marker(store.name, systemImage: "cart", coordinate: store.coordinate)
.annotationTitles(.hidden) // Hide titles at low zoom
}
}
.mapStyle(.standard(pointsOfInterest: .excludingAll))
```
For custom clustering behavior with `MKMapView` (UIKit interop), set
`clusteringIdentifier` on `MKMarkerAnnotationView`.
---
## MapKit with MKMapItem Utilities
### Open in Apple Maps
```swift
let item = MKMapItem(placemark: MKPlacemark(coordinate: coordinate))
item.name = "Destination"
item.openInMaps(launchOptions: [
MKLaunchOptionsDirectionsModeKey: MKLaunchOptionsDirectionsModeDriving
])
```
### Distance Calculation
```swift
func distanceBetween(_ a: CLLocationCoordinate2D,
_ b: CLLocationCoordinate2D) -> CLLocationDistance {
let locA = CLLocation(latitude: a.latitude, longitude: a.longitude)
let locB = CLLocation(latitude: b.latitude, longitude: b.longitude)
return locA.distance(from: locB) // meters
}
```
### Format Distance for Display
```swift
let formatter = MKDistanceFormatter()
formatter.unitStyle = .abbreviated
let text = formatter.string(fromDistance: 1500) // "0.9 mi" or "1.5 km"
```
---
## iOS 26 New APIs
### MKGeocodingRequest
Convert an address string to map items with richer data than `CLGeocoder`:
```swift
@available(iOS 26, *)
func geocodeAddresses(_ addresses: [String]) async -> [MKMapItem] {
var items: [MKMapItem] = []
for address in addresses {
guard let request = MKGeocodingRequest(addressString: address) else { continue }
if let mapItems = try? await request.mapItems {
items.append(contentsOf: mapItems)
}
}
return items
}
```
### MKReverseGeocodingRequest
Convert coordinates to map items with `MKAddress`:
```swift
@available(iOS 26, *)
func reverseGeocode(_ coordinate: CLLocationCoordinate2D) async -> MKAddress? {
let location = CLLocation(latitude: coordinate.latitude,
longitude: coordinate.longitude)
guard let request = MKReverseGeocodingRequest(location: location) else {
return nil
}
let mapItems = try? await request.mapItems
return mapItems?.first?.address
}
```
### MKAddress and MKAddressRepresentations
`MKAddress` provides full and short address strings. Use an `MKMapItem`'s
`MKAddressRepresentations` to format addresses for different contexts:
```swift
@available(iOS 26, *)
func formatAddress(for item: MKMapItem) -> String {
// Use address representations for locale-aware formatting
item.addressRepresentations?.fullAddress(includingRegion: true, singleLine: true)
?? item.address?.fullAddress
?? ""
}
```
### PlaceDescriptor (via GeoToolbox)
Create place references from coordinates when you do not have a Place ID:
```swift
import GeoToolbox
@available(iOS 26, *)
func mapItem(for myCoordinate: CLLocationCoordinate2D) async throws -> MKMapItem {
let descriptor = PlaceDescriptor(
representations: [.coordinate(myCoordinate)],
commonName: "My Favorite Cafe"
)
let request = MKMapItemRequest(placeDescriptor: descriptor)
return try await request.mapItem
}
// Use mapItem with any MapKit API: Marker(item:), directions, place cards
```
### Cycling Directions (iOS 14+)
```swift
func cyclingRoute(to destination: MKMapItem) async throws -> MKRoute? {
let request = MKDirections.Request()
request.source = .forCurrentLocation()
request.destination = destination
request.transportType = .cycling
let response = try await MKDirections(request: request).calculate()
return response.routes.first
}
```
---
## User Location Display
Show the user's position with the built-in blue dot:
```swift
Map(position: $position) {
UserAnnotation() // Blue dot with accuracy ring
// ... other content
}
.mapControls {
MapUserLocationButton() // Button to re-center on user
}
```
`UserAnnotation()` requires location authorization. If authorization is
denied, the annotation does not appear and no error is thrown.
---
## Map in a List or ScrollView
When embedding a `Map` inside a `ScrollView`, disable map gestures that
conflict with scrolling:
```swift
ScrollView {
Map(position: $position, interactionModes: []) {
Marker("Location", coordinate: coord)
}
.frame(height: 200)
.clipShape(.rect(cornerRadius: 12))
Text("Details below the map...")
}
```
Use `interactionModes: []` for a fully static map thumbnail or
`interactionModes: [.zoom]` to allow pinch-to-zoom without pan conflicts.
---
## Coordinate Utilities
### Region from an array of coordinates
```swift
func regionForCoordinates(_ coords: [CLLocationCoordinate2D]) -> MKCoordinateRegion {
guard !coords.isEmpty else {
return MKCoordinateRegion()
}
var minLat = coords[0].latitude
var maxLat = coords[0].latitude
var minLon = coords[0].longitude
var maxLon = coords[0].longitude
for coord in coords {
minLat = min(minLat, coord.latitude)
maxLat = max(maxLat, coord.latitude)
minLon = min(minLon, coord.longitude)
maxLon = max(maxLon, coord.longitude)
}
let center = CLLocationCoordinate2D(
latitude: (minLat + maxLat) / 2,
longitude: (minLon + maxLon) / 2
)
let span = MKCoordinateSpan(
latitudeDelta: (maxLat - minLat) * 1.3, // 30% padding
longitudeDelta: (maxLon - minLon) * 1.3
)
return MKCoordinateRegion(center: center, span: span)
}
```
### CLLocationCoordinate2D Equatable conformance
`CLLocationCoordinate2D` does not conform to `Equatable` by default.
Extend it when needed for comparisons:
```swift
extension CLLocationCoordinate2D: @retroactive Equatable {
public static func == (lhs: Self, rhs: Self) -> Bool {
lhs.latitude == rhs.latitude && lhs.longitude == rhs.longitude
}
}
```
Note: Use `@retroactive` (Swift 5.10+) to silence the warning about
conforming types from other modules.
---
## Accessibility
### Marker accessibility
`Marker` views include built-in VoiceOver support using the title string.
Add `.accessibilityLabel` for richer descriptions:
```swift
Marker(store.name, coordinate: store.coordinate)
.accessibilityLabel("\(store.name), \(store.distanceText) away")
```
### Map accessibility
Add a concise description of the map purpose:
```swift
Map { ... }
.accessibilityElement()
.accessibilityLabel("Store locations map showing \(stores.count) stores")
```
---
## References
- Apple docs: [MapKit for SwiftUI](https://sosumi.ai/documentation/MapKit/MapKit-for-SwiftUI)
- Apple docs: [Map](https://sosumi.ai/documentation/MapKit/Map)
- Apple docs: [MapCameraPosition](https://sosumi.ai/documentation/MapKit/MapCameraPosition)
- Apple docs: [MKLocalSearch](https://sosumi.ai/documentation/MapKit/MKLocalSearch)
- Apple docs: [MKDirections](https://sosumi.ai/documentation/MapKit/MKDirections)
- Apple docs: [MKLookAroundScene](https://sosumi.ai/documentation/MapKit/MKLookAroundScene)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |