This skill maps iOS SwiftUI navigation constructs to their Android Jetpack Compose equivalents.
Official Reference Links:
Prerequisites
Before using this skill, you Must ensure the following prerequisites are met:
- Source Context: Access to the existing iOS SwiftUI implementation (using
NavigationStackorNavigationView) is Mandatory. - Software Requirements: Kotlin 1.9.20+ (or Kotlin 2.0+), Kotlin
Serialization Plugin (
org.jetbrains.kotlin.plugin.serialization), Android Gradle Plugin (AGP) 8.0+, and Jetpack Compose Navigation (androidx.navigation:navigation-compose:2.8.0+, required for type-safe route serialization) are Mandatory. - Kotlin Knowledge: Familiarity with Kotlin Serialization is Mandatory for defining type-safe routes.
Limitations
This skill has the following limitations:
- Basic Stack Navigation: This skill primarily covers stack-based navigation (Push/Pop). It does not cover complex split views in detail.
- Version Focus: The examples are tailored for Jetpack Navigation 2.8.0+ which supports type-safe routing via Kotlin Serialization.
Glossary
| iOS Term | Android/Compose Equivalent | Definition |
|---|---|---|
NavigationStack |
NavHost |
The component that renders the UI based on the current navigation state and defines the navigation graph. |
NavigationLink |
navController.navigate() |
The action that triggers a transition to a new screen. |
UINavigationController |
NavController |
The central API that manages app navigation, holding the backstack. |
navigationDestination |
composable<T> destination |
The mapping of a route key to a specific Composable screen in the graph. |
Environment(\.dismiss) |
navController.popBackStack() |
The action to navigate back or dismiss the current screen. |
.navigationDestination(for:) |
@Serializable data class |
The definition of a route and its parameters using serialization. |
Setup & Dependencies
You Must add the following dependencies to your build.gradle.kts file to
enable type-safe navigation:
dependencies {
implementation("androidx.navigation:navigation-compose:2.8.0")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3")
implementation("androidx.lifecycle:lifecycle-runtime-compose:2.8.0")
}
You Must also apply the Kotlin Serialization plugin in your
build.gradle.kts:
kotlin
plugins {
kotlin("plugin.serialization") version "1.9.20" // Match your Kotlin version
}
Instructions: Mapping Concepts
1. Defining Routes
Map iOS dynamic destination resolution to Android @Serializable data classes
for type safety.
- Input: A destination identifier and its parameters.
- Output: A type-safe route definition.
iOS
swift
// In iOS, routes are often resolved dynamically via types
.navigationDestination(for: Profile.self) { profile in
ProfileView(id: profile.id)
}
Android ```kotlin // In Compose 2.8.0+, routes are defined by serializable objects @Serializable data class ProfileRoute(val id: String)
@Serializable object HomeRoute ```
2. Setting up the Navigation Graph
Map iOS NavigationStack to Android NavHost.
- Input: A
NavControllerinstance and a start destination. - Output: A rendered UI based on the current destination in the graph.
iOS
swift
NavigationStack {
ContentView()
}
Android ```kotlin val navController = rememberNavController()
NavHost(navController = navController, startDestination = HomeRoute) {
composable
3. Navigating to a Destination
Map iOS NavigationLink to navController.navigate().
- Input: The target route object with arguments.
- Output: The backstack is updated, and the app navigates to the new screen.
iOS
swift
NavigationLink(value: user) {
Text("View Profile")
}
Android
kotlin
// Triggered via callback from the View to maintain decoupling
onProfileClick = { id ->
navController.navigate(ProfileRoute(id))
}
4. Back Navigation
Map iOS dismiss environment to Android popBackStack().
- Input: None.
- Output: The top screen is removed from the backstack.
iOS
swift
@Environment(\.dismiss) var dismiss
// ...
dismiss()
Android
kotlin
navController.popBackStack()
5. Handling Deep Links
Map iOS deep link handling to Compose type-safe deep links.
- Input: A deep link URL pattern.
- Output: Automatic navigation to the screen when the app is opened via link.
iOS
swift
.onOpenURL { url in
// Handle URL manually
}
Android ```kotlin val deepLinkUri = "https://example.com/profile/{id}"
composable
6. Tab-Based Navigation (Bottom Navigation)
Map iOS TabView to Android Compose NavigationBar with state preservation.
- Input: A list of top-level destinations and the
NavController. - Output: A persistent bottom bar that switches screens while retaining their scroll state.
iOS
swift
TabView {
HomeView()
.tabItem { Label("Home", systemImage: "house") }
SettingsView()
.tabItem { Label("Settings", systemImage: "gear") }
}
Android ```kotlin val items = listOf(HomeRoute, SettingsRoute) val navController = rememberNavController()
Scaffold( bottomBar = { NavigationBar { val navBackStackEntry by navController.currentBackStackEntryAsState() val currentDestination = navBackStackEntry?.destination
items.forEach { screen ->
NavigationBarItem(
icon = { /* Add appropriate icon */ },
label = { Text(stringResource(screen.labelRes)) }, // @StringRes on each route
selected = currentDestination?.hierarchy?.any {
it.hasRoute(screen::class)
} == true,
onClick = {
navController.navigate(screen) {
// Pop up to the start destination of the graph to
// avoid building up a large stack of destinations
// on the back stack as users select items
popUpTo(navController.graph.findStartDestination().id) {
saveState = true
}
// Avoid multiple copies of the same destination when
// reselecting the same item
launchSingleTop = true
// Restore state when reselecting a previously selected item
restoreState = true
}
}
)
}
}
}
) { innerPadding ->
NavHost(navController, startDestination = HomeRoute, Modifier.padding(innerPadding)) {
composable
7. Custom Transitions
Map iOS transition animations to Compose Navigation transition parameters.
- Input: Navigation action triggering a screen change.
- Output: Visual transition effect (e.g., slide, fade) applied to the entering and exiting screens.
iOS
swift
// iOS typically uses system defaults or complex UIViewControllerTransitioningDelegate
NavigationStack {
// ...
}
// SwiftUI transitions are often defined on the view itself
.transition(.slide)
Android
kotlin
composable<ProfileRoute>(
enterTransition = {
slideIntoContainer(
AnimatedContentTransitionScope.SlideDirection.Left,
animationSpec = tween(500)
)
},
exitTransition = {
slideOutOfContainer(
AnimatedContentTransitionScope.SlideDirection.Left,
animationSpec = tween(500)
)
},
popEnterTransition = {
slideIntoContainer(
AnimatedContentTransitionScope.SlideDirection.Right,
animationSpec = tween(500)
)
},
popExitTransition = {
slideOutOfContainer(
AnimatedContentTransitionScope.SlideDirection.Right,
animationSpec = tween(500)
)
}
) { backStackEntry ->
val profile = backStackEntry.toRoute<ProfileRoute>()
ProfileScreen(id = profile.id)
}
8. Nested Navigation Graphs
Map iOS child coordinators or separate flows to Compose nested navigation graphs.
- Input: A group of related destinations.
- Output: A modular, nested graph within the main navigation graph.
iOS
swift
// iOS handles this via child coordinators or separate NavigationStacks
Android ```kotlin // Define a route for the graph itself @Serializable object ProfileGraph
NavHost(navController, startDestination = HomeRoute) {
composable
// Nested graph
navigation
9. Returning a Result to the Previous Screen
Map iOS callback patterns or delegates to Compose saved state handle results.
- Input: A screen that needs to return data.
- Output: Data is passed back to the previous screen in the backstack.
iOS
swift
// iOS typically uses delegates or closures to return data
Android ```kotlin // In the destination screen that returns a result val result = "New Data" navController.previousBackStackEntry?.savedStateHandle?.set("key", result) navController.popBackStack()
// In the source screen that is waiting for a result
val navBackStackEntry = navController.currentBackStackEntry
val resultFlow = navBackStackEntry?.savedStateHandle?.getStateFlow
LaunchedEffect(result) {
if (result != null) {
// Process the result
// ...
// Clear the result after consuming it
navBackStackEntry?.savedStateHandle?.remove
Quality Control: Antipatterns
DO
- DO use
@Serializabledata classes or objects for all routes to ensure type safety and prevent runtime crashes from missing arguments. - DO pass lambdas for navigation events (e.g.,
onNavigate) instead of passing theNavControllerinstance directly to child Composables. - DO use
toRoute<T>()to extract arguments in the destination lambda.
DON'T
- DON'T assume navigation state is automatically preserved across process death without saving the backstack state properly.
- DON'T hardcode string paths for routes (e.g.,
navigate("profile/\(id)")); always use the type-safe object approach. - DON'T forget to declare an
<intent-filter>in yourAndroidManifest.xmlfor each deep link. ThenavDeepLinkcomposable parameter only handles in-app routing; the manifest entry is mandatory for the app to respond to external URLs.
NEVER
- NEVER attempt to share navigation routing graphs in Kotlin Multiplatform
(KMP) if it forces you to compromise on using platform-native capabilities
like
NavigationSplitViewon iOS. Failure to do so may lead to degraded user experience. - NEVER pass the
NavControllerinstance directly as a parameter to generic composable screens to ensure proper decoupling and testability.