Skip to main content
affpapa.org
RU EN
skill CX Codex

mapbox-navigation-patterns — Claude Code skill for Mapbox routing

Tells your agent how to wire up turn-by-turn navigation, multi-stop routes and voice guidance on Mapbox.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add mapbox/mapbox-agent-skills --skill mapbox-navigation-patterns -a claude-code
Open on GitHub

What mapbox-navigation-patterns does

This skill covers the navigation side of Mapbox: route calculation, turn-by-turn instructions, alternative routes, delivery optimization and live traffic. It ships as a set of reference files split by platform — Directions API for the web, Navigation SDK for iOS and Android, a separate file on Android performance antipatterns, plus notes on route caching and error handling.

The main fork is spelled out in the skill itself: web apps and plain route display mean Directions API with pay-per-request pricing, while native turn-by-turn and voice guidance require a Navigation SDK billed by MAU. Directions API accepts up to 25 waypoints, so long delivery chains either get split or move to the Optimization API. There is no voice guidance on the web at all, which is worth deciding on before you commit to a browser build.

For iOS the skill recommends starting with a SwiftUI shell and a wrapped NavigationViewController through UIViewControllerRepresentable, and only going fully custom with Core UI when that is explicitly wanted. Before writing code you need the SPM packages MapboxNavigationCore and MapboxNavigationUIKit, an MBXAccessToken, location permissions and the background audio and location modes.

What it helps with

  • add turn-by-turn navigation to a mobile app
  • draw a route with directions on a web map
  • reorder stops for a delivery route
  • enable voice guidance in a given language
  • factor live traffic into an ETA

Example prompts for the agent

  • I need turn-by-turn navigation in a SwiftUI iOS app
  • Show a route with turn-by-turn instructions on a web map using the Directions API
  • Add voice guidance and real-time rerouting to the Android app

How to install mapbox-navigation-patterns

1Skills CLI (Vercel)

npx skills add mapbox/mapbox-agent-skills --skill mapbox-navigation-patterns -a claude-code

2Manually: put the files in place

~/.claude/skills/mapbox-navigation-patterns/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mapbox-navigation-patterns/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mapbox-navigation-patterns

How do I install mapbox-navigation-patterns in Claude?

Run npx skills add mapbox/mapbox-agent-skills --skill mapbox-navigation-patterns -a claude-code. The skill file then lives at ~/.claude/skills/mapbox-navigation-patterns/SKILL.md.

What does mapbox-navigation-patterns do?

It gives the agent implementation patterns for Mapbox navigation: route calculation, turn-by-turn instructions, multi-stop trips, traffic data and voice guidance.

Do I need a Mapbox token to use it?

The iOS path needs an MBXAccessToken, location permissions and the background audio and location modes. Stable Core and UIKit releases do not need a .netrc download token.

Source text

SKILL.md · MIT 
---
name: mapbox-navigation-patterns
description: Navigation implementation patterns for turn-by-turn directions, route optimization, real-time traffic, multi-stop routing, and voice guidance across web, iOS, and Android platforms
---

# Mapbox Navigation Patterns

Expert guidance for implementing navigation and routing features using Mapbox Directions API and Navigation SDKs. Covers turn-by-turn navigation, route optimization, real-time traffic integration, multi-stop routing, and navigation UI components.

## Use This Skill When

User says things like:

- "I need turn-by-turn navigation in my app"
- "How do I add driving directions?"
- "I want to show a route on the map"
- "I need multi-stop routing"
- "How do I add voice guidance?"
- "I want real-time traffic updates"
- "I need to optimize delivery routes"

## Product Overview

### Directions API (REST)

**Best for:** Web applications, simple routing, backend route calculation

**Features:**

- Route calculation (driving, walking, cycling, traffic)
- Alternative routes
- Turn-by-turn instructions
- Multi-stop routing (up to 25 waypoints)
- Route optimization
- Real-time traffic data
- Avoid specific roads/areas

**Pricing:** Pay per request

### Navigation SDK for iOS

**Best for:** Native iOS apps with turn-by-turn navigation

**Defaults:** SwiftUI app shell + wrap drop-in `NavigationViewController` via `UIViewControllerRepresentable` (official getting-started path). Use a fully custom Core UI ([CoreSDKExample](https://github.com/mapbox/mapbox-navigation-ios/tree/main/Examples/CoreSDKExample)) only when the user explicitly wants to build their own nav chrome.

**Before coding:** SPM (`MapboxNavigationCore` + `MapboxNavigationUIKit`), `MBXAccessToken`, location permissions, background `audio`/`location` — see [install guide](https://docs.mapbox.com/ios/navigation/guides/install/) and the iOS reference checklist. Stable Core/UIKit releases do not need a `.netrc` download token.

**Features:**

- Drop-in turn-by-turn UI (`NavigationViewController`) — default
- Optional fully custom Core UI (route progress / banner publishers)
- Voice guidance (30+ languages)
- Real-time rerouting
- Traffic-aware routing
- Offline maps and routing
- Route progress tracking
- Speed limit display

**Pricing:** Monthly Active Users (MAU) based

### Navigation SDK for Android

**Best for:** Native Android apps with turn-by-turn navigation

**Features:**

- Complete turn-by-turn navigation UI
- Voice guidance (30+ languages)
- Real-time rerouting
- Traffic-aware routing
- Offline maps and routing
- Custom UI components
- Route progress tracking
- Speed limit display

**Pricing:** Monthly Active Users (MAU) based

## Decision Guide

### Choose Directions API when:

- ✅ Web application
- ✅ Simple route display (no turn-by-turn)
- ✅ Backend route calculation
- ✅ Route planning and optimization
- ✅ Multi-stop routing
- ✅ Don't need voice guidance

### Choose Navigation SDK when:

- ✅ Native mobile app (iOS/Android)
- ✅ Need turn-by-turn navigation
- ✅ Need voice guidance
- ✅ Need navigation UI components
- ✅ Need offline navigation
- ✅ Need real-time rerouting
- ✅ Building a navigation/delivery app

## Implementation Patterns

- **[references/web-directions-api.md](references/web-directions-api.md)** - Directions API patterns for the web: basic route display, turn-by-turn instructions, alternative routes, multi-stop routing, route optimization, and congestion-based route coloring
- **[references/ios-navigation-sdk.md](references/ios-navigation-sdk.md)** - When: iOS turn-by-turn, setup, default SwiftUI + wrapped `NavigationViewController`, Core opt-in, example catalog
- **[references/ios-navigation-specialized.md](references/ios-navigation-specialized.md)** - When: multi-stop, route line, camera, road cameras, route alerts, or `NavigationMapView` customization
- **[references/android-navigation-sdk.md](references/android-navigation-sdk.md)** - Navigation SDK for Android: basic turn-by-turn navigation, custom navigation UI, route line rendering, maneuver arrows, navigation camera, voice guidance
- **[references/android-performance-antipatterns.md](references/android-performance-antipatterns.md)** - Android Navigation SDK performance and correctness antipatterns: Native Route Object traversal costs, threading, memory/lifecycle leaks, route management correctness, frequent-callback rendering efficiency, and Coordination API lifecycle
- **[references/best-practices.md](references/best-practices.md)** - Route caching, error handling, performance optimization, user experience, and common use cases (delivery routing, ride-sharing ETAs, walking/cycling directions)

## Related Skills

- **mapbox-search-integration**: Address search and geocoding
- **mapbox-web-performance-patterns**: Optimizing navigation performance
- **mapbox-ios-patterns**: iOS-specific integration patterns
- **mapbox-android-patterns**: Android-specific integration patterns
- **mapbox-token-security**: Securing your access tokens

## Resources

- [Directions API Documentation](https://docs.mapbox.com/api/navigation/directions/)
- [Navigation SDK for iOS](https://docs.mapbox.com/ios/navigation/)
- [Navigation SDK for Android](https://docs.mapbox.com/android/navigation/)
- [Optimization API Documentation](https://docs.mapbox.com/api/navigation/optimization/)
- [Map Matching API](https://docs.mapbox.com/api/navigation/map-matching/)
- [Navigation Products Overview](https://docs.mapbox.com/help/getting-started/navigation/)

## Quick Decision Guide

**User says: "I need directions"**

- Web app → Use Directions API
- Mobile app → Use Navigation SDK

**User says: "I need turn-by-turn navigation"**

- iOS → Navigation SDK for iOS (SwiftUI + wrapped `NavigationViewController` by default; Core custom UI only if requested)
- Android → Navigation SDK for Android
- Web → Use Directions API + custom UI (no voice guidance)

**User says: "I need to optimize delivery routes"**
→ Use Optimization API (multi-stop route optimization)

**User says: "I need real-time traffic"**
→ Use `driving-traffic` profile with Directions API or Navigation SDK

**User says: "I need voice guidance"**
→ Must use Navigation SDK (iOS/Android only)

**User says: "Directions API or Navigation SDK?"**
→ Native turn-by-turn / voice → Navigation SDK (**MAU** pricing). Web / route display only → Directions API (**pay-per-request**).

© mapbox · MIT · mapbox/mapbox-agent-skills

Similar skills

Everything for Mobile →
maplibre-mapbox-migration maplibre Guides the transition from Mapbox GL JS to MapLibre GL JS across imports, CSS, and tile configurations. Useful when moving away from Mapbox licensing. CX Codex +1 464installs navigation-patterns Owl-Listener Helps select and design navigation patterns such as tab bars, sidebars, and breadcrumbs. Useful when mapping user journeys across mobile and desktop interfaces. CX Codex +1 1,800installs navigation-event Google LLC Intercepts back gestures and sets up Predictive Back animations via androidx.navigationevent in Compose Android. Helps migrate from legacy BackHandler. CX Codex +1 546installs swiftui-navigation dpearson2699 Provides SwiftUI navigation architectures, covering typed stacks, multi-column layouts, sheets, and tabs. Useful when structuring navigation state across iOS and macOS apps. CX Codex +1 4,400installs navigation-3 Google LLC A reference skill for Jetpack Navigation 3: the move from Navigation 2 plus ready recipes for deep links, multiple back stacks, scenes, Hilt and ViewModel. CX Codex +1 3,200installs swiftui-ui-patterns official OpenAI This skill helps build and refactor SwiftUI interfaces, from navigation and state to layouts and controls. Use it for new screens or changes to an existing project. CX Codex GP ChatGPT 114installs

From the same set19

mapbox-store-locator-patterns Store locator patterns for Mapbox GL JS. Helps agents implement marker layers, synchronized lists, and Turf distance calculations without DOM overhead. CX Codex +1 1,700installs mapbox-ios-patterns Official integration patterns for Mapbox Maps SDK v11 on iOS in Swift, SwiftUI and UIKit. Useful when you need a map, markers or GeoJSON data in an app. CX Codex +1 1,500installs mapbox-mcp-devkit-patterns A skill that shows your AI assistant how to drive the Mapbox MCP DevKit Server: styles, tokens, validation and docs lookup from the chat. CX Codex +1 1,500installs mapbox-maplibre-migration Walks a project from MapLibre GL JS to Mapbox GL JS: package swap, imports, styles, token. Useful when self-hosted tiles or community support stop being enough. CX Codex +1 1,400installs mapbox-mcp-runtime-patterns Guides agents on integrating Mapbox MCP Server into AI frameworks. Helps models choose between local Turf.js math and live Mapbox routing APIs. CX Codex +1 1,400installs mapbox-google-maps-migration A skill that walks an agent through porting a project from Google Maps Platform to Mapbox GL JS, with API equivalents and a migration order. CX Codex +1 1,400installs mapbox-android-patterns A skill with official Mapbox Maps SDK v11 integration patterns for Android: map setup, markers, user location, camera control. Useful when the agent builds a map screen. CX Codex +1 1,400installs mapbox-flutter-patterns Skill with official integration patterns for the Mapbox Maps Flutter SDK. Helps set up maps on iOS and Android, add markers, control the camera, and load GeoJSON data. CX Codex +1 787installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor