Kotlin Parcelize Runtime

The Kotlin Parcelize Runtime provides essential annotations and utilities for the Kotlin Parcelize compiler plugin. It enables automatic generation of Android Parcelable implementations through annotations, eliminating boilerplate code while maintaining type safety and performance for Android development.

Package Information

• Package Name: org.jetbrains.kotlin:kotlin-parcelize-runtime
• Package Type: maven
• Language: Kotlin
• Installation:
  • Gradle: implementation("org.jetbrains.kotlin:kotlin-parcelize-runtime:2.2.0")
  • Maven:

    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-parcelize-runtime</artifactId>
        <version>2.2.0</version>
    </dependency>

Core Imports

import kotlinx.parcelize.Parcelize
import kotlinx.parcelize.IgnoredOnParcel
import kotlinx.parcelize.RawValue
import kotlinx.parcelize.WriteWith
import kotlinx.parcelize.TypeParceler
import kotlinx.parcelize.Parceler
import kotlinx.parcelize.parcelableCreator
import kotlinx.parcelize.DataClass
import android.os.Parcel // Required for custom Parceler implementations

Basic Usage

import android.os.Parcelable
import kotlinx.parcelize.Parcelize
import kotlinx.parcelize.IgnoredOnParcel

@Parcelize
data class User(
    val id: String,
    val name: String,
    val email: String,
    @IgnoredOnParcel val password: String = ""
) : Parcelable

// Usage
val user = User("123", "John Doe", "john@example.com")
// writeToParcel(), describeContents(), and CREATOR are automatically generated

Capabilities

Basic Parcelize Annotation

The core annotation that instructs the Kotlin compiler to generate Parcelable implementation automatically.

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.BINARY)
annotation class Parcelize

Used on classes that implement android.os.Parcelable to automatically generate:

• writeToParcel() method
• describeContents() method
• CREATOR factory class

Only primary constructor properties are serialized.

Property Exclusion

Exclude specific properties from parcel serialization.

@Target(AnnotationTarget.PROPERTY)
@Retention(AnnotationRetention.SOURCE)
annotation class IgnoredOnParcel

Properties annotated with @IgnoredOnParcel will not be stored in the parcel during serialization.

Raw Value Serialization

Handle complex types using raw value serialization.

@Target(AnnotationTarget.TYPE)
@Retention(AnnotationRetention.BINARY)
annotation class RawValue

Writes property values using android.os.Parcel.writeValue(). Serialization may fail at runtime depending on the actual property value type.

Usage example:

@Parcelize
data class ComplexData(
    val regularField: String,
    val complexField: @RawValue Any
) : Parcelable

Custom Parceler Integration

Specify custom parcelers for type-specific serialization.

@Retention(AnnotationRetention.SOURCE)
@Target(AnnotationTarget.TYPE)
annotation class WriteWith<P : Parceler<*>>

@Retention(AnnotationRetention.SOURCE)
@Repeatable
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY)
annotation class TypeParceler<T, P : Parceler<in T>>

• @WriteWith: Specifies parceler for the annotated type
• @TypeParceler: Specifies parceler for a particular type T, can be repeated

Custom Parceler Interface

Implement custom serialization logic for complex types.

interface Parceler<T> {
    /**
     * Writes the [T] instance state to the [parcel].
     */
    fun T.write(parcel: Parcel, flags: Int)

    /**
     * Reads the [T] instance state from the [parcel], constructs the new [T] instance and returns it.
     */
    fun create(parcel: Parcel): T

    /**
     * Returns a new [Array]<T> with the given array [size].
     */
    fun newArray(size: Int): Array<T>
}

Usage example:

object DateParceler : Parceler<Date> {
    override fun Date.write(parcel: Parcel, flags: Int) {
        parcel.writeLong(time)
    }

    override fun create(parcel: Parcel): Date {
        return Date(parcel.readLong())
    }

    override fun newArray(size: Int): Array<Date> {
        throw NotImplementedError("Generated by Android Extensions automatically")
    }
}

@Parcelize
@TypeParceler<Date, DateParceler>
data class Event(
    val name: String,
    val date: Date
) : Parcelable

Parcelable Creator Access

Programmatically access the CREATOR field of Parcelable classes.

inline fun <reified T : Parcelable> parcelableCreator(): Parcelable.Creator<T>

Reads the CREATOR field of the given Parcelable class with direct field access optimization.

Throws: IllegalArgumentException with message "Could not access CREATOR field in class {ClassName}" if CREATOR field cannot be accessed.

Usage example:

val creator = parcelableCreator<User>()
val userFromParcel = creator.createFromParcel(parcel)

Experimental Data Class Serialization

Enable serialization of non-Parcelable data classes (experimental feature).

@Target(AnnotationTarget.TYPE)
@Retention(AnnotationRetention.SOURCE)
@Experimental
annotation class DataClass

@RequiresOptIn("This feature is experimental and requires explicit opt-in")
annotation class Experimental

When a type is annotated with @DataClass, data classes contained inside it will be serialized even if they are not Parcelable. The serialization format is equivalent to what would be generated if the data class was annotated with @Parcelize.

Usage example:

data class NonParcelableData(val value: String)

@Parcelize
data class Container(
    val data: @DataClass NonParcelableData
) : Parcelable

Internal Compiler Utilities

object DirectInitializerMarker

Internal marker object used by the compiler for optimization purposes. Not intended for direct use in application code.

Error Handling

• IllegalArgumentException: Thrown by parcelableCreator() when CREATOR field cannot be accessed
• NotImplementedError: Thrown by default Parceler.newArray() implementation
• Runtime serialization failures: May occur with @RawValue depending on actual property value types

Dependencies

• kotlin-stdlib: Core Kotlin standard library
• com.google.android:android: Android framework (compile-only dependency)