Jetpack Navigation 3: Complete Android Developer Guide 2025

Profile photo of Brahim Oubbad
Front-End Developer
• Estimated read time:
Diagram showing the architecture of Navigation 3 in Jetpack Compose, including a back stack of navigation keys, an entry provider, and a NavDisplay rendering the current screen.
How Navigation 3 in Jetpack Compose uses a back stack, entry provider, and NavDisplay to manage navigation state and display UI content reactively.

The Android navigation landscape has undergone a revolutionary transformation with the introduction of Jetpack Compose Navigation 3. If you've been wrestling with the limitations of XML-based navigation or finding Navigation 2 for Compose somewhat cumbersome, you're about to discover why compose navigation 3 is being hailed as a game-changer in the Android development community.

Introduction: The Evolution of Compose Navigation

Remember the days of XML navigation graphs? Those sprawling files that became unmanageable as your app grew? Or perhaps you've experienced the friction of Navigation 2 for Compose, where type safety felt like an afterthought and complex navigation flows required workarounds that made your code feel fragile.

What is Compose Navigation 3? It's Google's answer to the fundamental pain points that have plagued Android navigation for years. While Navigation 2 introduced Compose support, it still carried baggage from its XML origins. Navigation 3 was built from the ground up with Compose-first principles.

Why Navigation 3 Was Necessary

The previous navigation solutions suffered from several critical issues:

  • Type Safety Gaps: Passing arguments between destinations was error-prone
  • Back Stack Complexity: Developers had limited control over navigation state
  • Boilerplate Heavy: Simple navigation required excessive setup code
  • Testing Challenges: Navigation logic was difficult to unit test effectively

Navigation 3 addresses these pain points with a modern, declarative approach that puts you in complete control of your app's navigation flow. It's not just an incremental improvement—it's a fundamental rethinking of how navigation should work in Compose applications.

Core Concepts of Navigation 3 Demystified

Think of Navigation 3 as the conductor of an orchestra, where each component plays a specific role in creating a harmonious user experience. Let's break down the key players:

The Navigation 3 Parts

Component Role Navigation Purpose
Back Stack The stage where navigation happens Holds references to where users can navigate
entryProvider{} Current navigation state Represents the active destination
NavDisplay Renders the active destination Shows the current content to users

Setting Up Your Project for Jetpack Compose Navigation 3

Getting started with Compose Navigation 3 is simple. Follow these steps to add the necessary dependencies and set up your project.

1. Update libs.versions.toml

Add the required nav3 versions and libraries:

[versions]
nav3Core = "1.0.0-alpha01"
nav3Material = "1.0.0-SNAPSHOT"
nav3Lifecycle = "1.0.0-alpha01"
kotlinSerialization = "2.1.21"
kotlinxSerializationCore = "1.8.1"

[libraries]
# Core Navigation 3 libraries
androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "nav3Core" }
androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "nav3Core" }

# Optional add-ons
androidx-material3-navigation3 = { group = "androidx.compose.material3.adaptive", name = "adaptive-navigation3", version.ref = "nav3Material" }
androidx-lifecycle-viewmodel-navigation3 = { module = "androidx.lifecycle:lifecycle-viewmodel-navigation3", version.ref = "nav3Lifecycle" }

# Serialization support
kotlinx-serialization-core = { module = "org.jetbrains.kotlinx:kotlinx-serialization-core", version.ref = "kotlinxSerializationCore" }
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerializationCore" }

[plugins]
jetbrains-kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlinSerialization" }

2. Update build.gradle.kts

Apply the Kotlin Serialization plugin:

plugins {
    alias(libs.plugins.jetbrains.kotlin.serialization)
}

Add the dependencies: 

dependencies {
    implementation(libs.androidx.navigation3.ui)
    implementation(libs.androidx.navigation3.runtime)
    implementation(libs.androidx.lifecycle.viewmodel.navigation3)
    implementation(libs.androidx.material3.navigation3)

    // Serialization libraries
    implementation(libs.kotlinx.serialization.core)
    implementation(libs.kotlinx.serialization.json)
}

3. Update settings.gradle.kts

Because Navigation 3 is still in alpha/SNAPSHOT, you need to add the custom snapshot repository: 

dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://androidx.dev/snapshots/builds/[buildId]/artifacts/repository")
        }
        google()
        mavenCentral()
    }
}

How to Get the YOUR_BUILD_ID (Snapshot ID)

You can find the correct build ID from the AndroidX Snapshot Builds page.

  1. Go to: https://androidx.dev/
  2.  click on Snapshots to find recent snapshot builds.
  3. Copy the Build ID from the URL or the top of the page (e.g., 13551459).
  4. Replace [buildId] in the Maven URL.

For example:

url = uri("https://androidx.dev/snapshots/builds/13551459/artifacts/repository")

The Back Stack Concept

Navigation 3 models user movement using a back stack - a stack-based data structure that tracks where users can navigate. Think of it as a history of user actions: 

// Define your navigation destinations
sealed class Screen : NavKey {
    @Serializable
    data object Home : Screen()

    @Serializable
    data class Details(val id: String) : Screen()
}

@Composable
fun NavExample(
    modifier: Modifier = Modifier
) {
    // Create your back stack with initial destination
    val backStack = rememberNavBackStack<Screen>(Screen.Home)

    // Navigate forward - push to stack
    backStack.add(Screen.Details("123"))

    // Navigate back - pop from stack
    backStack.removeLastOrNull()
}

Why Use Keys Instead of Content?

Navigation 3's genius lies in using keys (lightweight references) instead of actual content:

  1. Performance: Faster navigation with minimal memory usage
  2. Persistence: Easy serialization for state saving
  3. Simplicity: Clean separation between navigation logic and UI content
  4. Scalability: Handles complex navigation flows effortlessly

Creating Your First Navigation 3 Implementation

Step 1: Define Your Navigation Keys

// Define your navigation destinations
sealed class Screen : NavKey {
    @Serializable
    data object Home : Screen()

    @Serializable
    data class Details(val id: String) : Screen()
}

Step 2: Implement NavDisplay

The NavDisplay composable observes your back stack and renders the appropriate content:

@Composable
fun NavExample(
    modifier: Modifier = Modifier
) {
    // Create your back stack with initial destination
    val backStack = rememberNavBackStack<Screen>(Screen.Home)

    NavDisplay(
        modifier = modifier,
        backStack = backStack,
        onBack = {
            // Navigate back - pop from stack
            backStack.removeLastOrNull()
        },
        entryProvider = entryProvider {}
    )
}

Step 3: Build Your Entry Provider

The entryProvider function converts keys into actual UI content. You have two approaches:

@Composable
fun NavExample(
    modifier: Modifier = Modifier
) {
    // Create your back stack with initial destination
    val backStack = rememberNavBackStack<Screen>(Screen.Home)

    NavDisplay(
        modifier = modifier,
        backStack = backStack,
        onBack = {
            // Navigate back - pop from stack
            backStack.removeLastOrNull()
        },
        entryProvider = entryProvider {
            entry<Screen.Home> {
                HomeScreen("Welcome to Nav3") {
                    Button(onClick = {
                        // Navigate forward - push to stack
                        backStack.add(Screen.Details("123"))
                    }) {
                        Text("Click to navigate")
                    }
                }
            }

            entry<Screen.Details> { key ->
                DetailsScree("Product ${key.id} ")
            }
        }
    )
}

Full Compose Navigation 3 Example

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.Button
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.navigation3.runtime.NavKey
import androidx.navigation3.runtime.entry
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay
import com.example.navigation3.ui.theme.Navigation3Theme
import kotlinx.serialization.Serializable


sealed class Screen : NavKey {
    // `@Serializable` is used here because navigation keys often need to be saved and restored.
    @Serializable
    data object Home : Screen()

    @Serializable
    data class Details(val id: String) : Screen()
}

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            Navigation3Theme {
                Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
                    NavExample()
                }
            }
        }
    }
}

@Composable
fun NavExample(
    modifier: Modifier = Modifier
) {
    // `rememberNavBackStack` creates a `NavBackStack` instance, persisting across recompositions and configuration changes.
    // `Screen` is the navigation key type, and `Screen.Home` is the initial destination.
    val backStack = rememberNavBackStack<Screen>(Screen.Home)

    NavDisplay(
        modifier = modifier,
        backStack = backStack,
        onBack = {
            // Navigate back - pop from stack
            backStack.removeLastOrNull()
        },
        entryProvider = entryProvider {
            entry<Screen.Home> {
                HomeScreen("Welcome to Nav3") {
                    Button(onClick = {
                        // Navigate forward - push to stack
                        backStack.add(Screen.Details("123"))
                    }) {
                        Text("Click to navigate")
                    }
                }
            }

            entry<Screen.Details> { key ->
                DetailsScree("Product ${key.id} ")
            }
        }
    )
}

@Composable
fun HomeScreen(message: String, content: @Composable () -> Unit) {
    Column(
        modifier = Modifier
            .fillMaxSize()
            .background(color = Color.Green),
        verticalArrangement = Arrangement.Center,
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(text = message)
        content()
    }
}

@Composable
fun DetailsScree(message: String) {
    Column(
        modifier = Modifier
            .fillMaxSize()
            .background(color = Color.Blue),
        verticalArrangement = Arrangement.Center,
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(text = message)
    }
}

Common Error Solutions

// Error: Type mismatch in navigation
// Solution: Use proper serializable routes
@Serializable
data class UserRoute(val id: String)

Comparing Navigation 3: How it Stacks Up

Navigation 3 vs Navigation 2

Feature Navigation 2 Navigation 3
Type Safety Limited Full support
Back Stack Control Restricted Complete ownership
Animation Support Basic Advanced
Testing Difficult Comprehensive
Code Verbosity High Reduced
Adaptive Navigation Not supported Full foldable/tablet support
Multi-pane Layouts Manual implementation Built-in adaptive patterns

Third-Party Alternatives

While libraries like Voyager and Compose Destinations offer alternatives, Navigation 3 provides:

  • Official Google support and maintenance
  • Seamless integration with other Jetpack libraries
  • Comprehensive documentation and community support
  • Long-term stability guarantees

The Future of Compose Navigation & Getting Involved

Navigation 3 represents just the beginning of modern Android navigation. Expected future enhancements include:

  • Enhanced shared element transitions
  • Improved multi-window support
  • Better integration with Compose Multiplatform
  • Advanced state restoration capabilities
  • Expanded adaptive navigation patterns for emerging form factors
  • AI-powered navigation optimization for different device types

Get Involved:

Conclusion: Why Navigation 3 is a Leap Forward

Jetpack Compose Navigation 3 isn't just an incremental update—it's a fundamental reimagining of how navigation should work in modern Android applications. With its type-safe routes, complete back stack control, and powerful animation capabilities, it addresses every major pain point that developers have experienced with previous navigation solutions.

The migration from Navigation 2 might seem daunting, but the benefits—cleaner code, better testing, improved type safety, and enhanced user experiences—make it a worthwhile investment. Whether you're building a simple app or a complex, multi-module application, Navigation 3 provides the tools and flexibility you need to create exceptional navigation experiences.

Start your journey with compose navigation 3 today, and experience the difference that thoughtful, developer-focused design can make in your Android applications. The future of Android navigation is here, and it's more powerful and developer-friendly than ever before.