How to Use Custom Parcelable Objects in Compose Navigation

How Did We Discover the Need for Custom Parcelables in Compose Navigation?

While working on a massive modernization project for a secure healthcare management application, our engineering team migrated the mobile routing layer to Jetpack Compose Navigation 2.8.0+. The goal was to leverage the new type-safe routing capabilities, replacing fragile string-based routes with robust Kotlin @Serializable data classes.

During testing, we encountered a situation where navigating from the patient list screen to the patient details screen caused an unexpected crash. Our route was defined as a sealed class containing a complex custom Parcelable object representing the patient’s encrypted profile data. While the new navigation library seamlessly handles primitive types, we realized it does not natively know how to serialize and deserialize custom parcelable objects out of the box.

In production environments, especially in healthcare where data integrity is critical, passing complex state safely between screens without memory leaks or crash loops is a top priority. This challenge inspired this article so other teams can avoid the same architectural oversight when adopting type-safe navigation in Jetpack Compose.

Why Does Jetpack Compose Navigation 2.8.0 Struggle with Parcelable Objects?

To understand the business use case, consider how data flows in a modern mobile application. In our healthcare platform, we needed to pass a comprehensive PatientProfile object—which was already annotated with @Parcelize—directly into our navigation graph. With Compose Navigation 2.8.0+, the architecture shifted from string interpolation to fully typed objects using Kotlin Serialization.

The issue appeared in the navigation graph definition. When a route data class contains a custom object, the underlying Compose Navigation component requires an explicit mapping to translate that object into a format suitable for the navigation bundle and potential deep link URIs. Without this translation layer, the compiler and runtime cannot infer how to break down a custom Parcelable into the underlying Bundle or URI string. For companies looking to hire app developer to create a mobile app, establishing these navigation fundamentals early prevents costly refactoring later in the project lifecycle.

What Were the Symptoms of Unregistered NavType Failures?

When we first implemented the route, our sealed class looked structurally sound:

@Serializable
sealed class AppRoute {
    @Serializable
    data class PatientDetails(val patientProfile: PatientProfile) : AppRoute()
}

However, when triggering the navigation event, the application immediately crashed. The logs revealed a java.lang.IllegalArgumentException, stating that the destination could not be found or that the navigation component could not cast our custom class to a recognized NavType.

The bottleneck was clear: while Kotlin Serialization knew how to handle the data class structurally, the Navigation component lacked the explicit NavType registry to bridge the gap between the @Serializable route and the Android Bundle mechanism. This oversight bypassed the type-safety benefits we were trying to implement.

How Did We Evaluate Approaches for Passing Complex Objects?

Before writing a custom implementation, we debated several architectural approaches to ensure we were making the right decision for the platform’s long-term maintainability.

Can We Revert to Passing Basic Primitive Identifiers?

The traditional recommendation in Android development is to pass only a unique ID (e.g., patientId) and fetch the full object from a local database or repository on the destination screen. While this is a solid best practice, our specific offline-first requirement meant the data was already transformed and held in memory. Forcing an unnecessary database read for a complex transient state would introduce UI latency.

Should We Use Activity-Scoped Shared ViewModels?

We considered hoisting the state into a shared ViewModel scoped to the underlying Activity. The list screen would update the shared state, and the details screen would observe it. However, this creates tight coupling between screens and complicates state cleanup, increasing the risk of memory leaks in a long-running session.

Can We JSON Serialize the Object as a String Argument?

Another workaround was converting the PatientProfile into a JSON string using Gson or Kotlinx Serialization, passing it as a standard string argument, and deserializing it on the other side. This approach felt hacky, risked hitting Intent size limits, and entirely defeated the purpose of adopting a type-safe navigation architecture.

Ultimately, we determined that extending the navigation system was the most robust path forward. When enterprise teams hire Android developers for complex mobile architecture, the expectation is to build solutions that extend framework capabilities rather than working around them.

How Do You Implement a Custom NavType for Parcelables?

The final implementation required us to define a custom NavType that instructs the Compose Navigation component on how to encode and decode our Parcelable object. This requires using both @Parcelize for Android state saving and @Serializable for Kotlin Serialization.

First, we ensured our data model was properly annotated:

@Serializable
@Parcelize
data class PatientProfile(
    val id: String,
    val name: String,
    val status: String
) : Parcelable

Next, we created the custom NavType. This involves overriding methods to handle both Bundle extraction (for standard navigation) and String parsing (for deep link support):

val PatientProfileType = object : NavType<PatientProfile>(isNullableAllowed = false) {
    
    override fun get(bundle: Bundle, key: String): PatientProfile? {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            bundle.getParcelable(key, PatientProfile::class.java)
        } else {
            @Suppress("DEPRECATION")
            bundle.getParcelable(key)
        }
    }
    override fun parseValue(value: String): PatientProfile {
        // Decode the URL-encoded JSON string back into the object
        return Json.decodeFromString(Uri.decode(value))
    }
    override fun serializeAsValue(value: PatientProfile): String {
        // Encode the object to JSON and URL-encode it for safe transport
        return Uri.encode(Json.encodeToString(value))
    }
    override fun put(bundle: Bundle, key: String, value: PatientProfile) {
        bundle.putParcelable(key, value)
    }
}

Finally, we registered this custom type in our Compose NavHost configuration. By using the typeMap parameter, we explicitly linked the Kotlin type to our custom NavType:

NavHost(navController = navController, startDestination = AppRoute.Home) {
    composable<AppRoute.PatientDetails>(
        typeMap = mapOf(typeOf<PatientProfile>() to PatientProfileType)
    ) { backStackEntry ->
        val route = backStackEntry.toRoute<AppRoute.PatientDetails>()
        PatientDetailsScreen(patientProfile = route.patientProfile)
    }
}

This implementation preserved strict type safety, handled deep linking correctly via JSON encoding, and utilized standard Android bundles for fast, in-memory navigation.

What Should Engineering Teams Learn from This Navigation Challenge?

Implementing type-safe navigation requires a deep understanding of how underlying Android frameworks interact with Kotlin capabilities. Here are the core actionable insights other engineering teams should apply:

• Understand the Bundle Limitations: Even though Compose Navigation feels like a pure Kotlin implementation, it still relies on standard Android Bundles under the hood. Complex objects must be parcelable.
• Support Deep Links Proactively: Always implement parseValue and serializeAsValue using URL-encoded JSON. Failing to encode the JSON string can break navigation if your object data contains special characters.
• Combine Annotations Carefully: A data class used in type-safe routing must be both @Serializable (for routing structure) and @Parcelize (for state saving and bundle transfer).
• Type Maps are Mandatory for Custom Objects: The navigation graph will not automatically infer your custom NavType. You must explicitly declare it in the typeMap of your composable destination.
• Avoid Overloading Navigation Arguments: While this technique works brilliantly for necessary data transfer, avoid passing massive payloads (like large images or lists of hundreds of items) to prevent TransactionTooLargeException.
• Prioritize Type Safety: Embracing type-safe routing eliminates the class of bugs associated with typos in string routes or missing intent extras.

How Can You Ensure Your Mobile Architecture Remains Scalable?

Migrating to Jetpack Compose Navigation 2.8.0+ is a significant step toward predictable, crash-free mobile applications. By defining a custom NavType, we successfully bridged the gap between Kotlin Serialization and Android’s native Parcelable mechanism, ensuring our healthcare platform maintained both strict data integrity and type safety. Businesses looking to hire Kotlin developers for robust app development should verify that their teams understand these granular architectural interactions. When you are ready to scale your application with engineering teams that look beyond basic implementation, we encourage you to hire software developer experts and contact us.

Social Hashtags

#JetpackCompose #ComposeNavigation #AndroidDevelopment #Kotlin #KotlinDevelopment #AndroidDevelopers #TypeSafeNavigation #Parcelable #NavType #KotlinSerialization #MobileAppDevelopment #SoftwareDevelopment