Parcelable implementation generator

The kotlin-parcelize plugin provides a Parcelable implementation generator.

To include support for Parcelable, add the Gradle plugin to your app's build.gradle file:

Groovy

plugins {
    id 'kotlin-parcelize'
}

Kotlin

plugins {
    id("kotlin-parcelize")
}

When you annotate a class with @Parcelize, a Parcelable implementation is automatically generated, as shown in the following example:

import kotlinx.parcelize.Parcelize

@Parcelize
class User(val firstName: String, val lastName: String, val age: Int): Parcelable

@Parcelize requires all serialized properties to be declared in the primary constructor. The plugin issues a warning on each property with a backing field declared in the class body. Also, you can't apply @Parcelize if some of the primary constructor parameters are not properties.

If your class requires more advanced serialization logic, write it inside a companion class:

@Parcelize
data class User(val firstName: String, val lastName: String, val age: Int) : Parcelable {
    private companion object : Parceler<User> {
        override fun User.write(parcel: Parcel, flags: Int) {
            // Custom write implementation
        }

        override fun create(parcel: Parcel): User {
            // Custom read implementation
        }
    }
}

Supported types

@Parcelize supports a wide range of types:

  • Primitive types (and their boxed versions)
  • Objects and enums
  • String, CharSequence
  • Duration
  • Exception
  • Size, SizeF, Bundle, IBinder, IInterface, FileDescriptor
  • SparseArray, SparseIntArray, SparseLongArray, SparseBooleanArray
  • All Serializable (including Date) and Parcelable implementations
  • Collections of all supported types: List (mapped to ArrayList), Set (mapped to LinkedHashSet), Map (mapped to LinkedHashMap)
    • Also a number of concrete implementations: ArrayList, LinkedList, SortedSet, NavigableSet, HashSet, LinkedHashSet, TreeSet, SortedMap, NavigableMap, HashMap, LinkedHashMap, TreeMap, ConcurrentHashMap
  • Arrays of all supported types
  • Nullable versions of all supported types

Custom Parcelers

If your type is not supported directly, you can write a Parceler mapping object for it.

class ExternalClass(val value: Int)

object ExternalClassParceler : Parceler<ExternalClass> {
    override fun create(parcel: Parcel) = ExternalClass(parcel.readInt())

    override fun ExternalClass.write(parcel: Parcel, flags: Int) {
        parcel.writeInt(value)
    }
}

You can apply external parcelers using @TypeParceler or @WriteWith annotations:

// Class-local parceler
@Parcelize
@TypeParceler<ExternalClass, ExternalClassParceler>()
class MyClass(val external: ExternalClass) : Parcelable

// Property-local parceler
@Parcelize
class MyClass(@TypeParceler<ExternalClass, ExternalClassParceler>() val external: ExternalClass) : Parcelable

// Type-local parceler
@Parcelize
class MyClass(val external: @WriteWith<ExternalClassParceler>() ExternalClass) : Parcelable

Create data from Parcel

In Java code, you can access the CREATOR field directly.

class UserCreator {
    static User fromParcel(Parcel parcel) {
        return User.CREATOR.createFromParcel(parcel);
    }
}

In Kotlin, you can't use the CREATOR field directly. Instead, use kotlinx.parcelize.parcelableCreator.

import kotlinx.parcelize.parcelableCreator

fun userFromParcel(parcel: Parcel): User {
    return parcelableCreator<User>().createFromParcel(parcel)
}

Skip properties from serialization

If you want to skip some property from being parcelized, use the @IgnoredOnParcel annotation. It can also be used on properties within a class's body to silence warnings about the property not being serialized. Constructor properties annotated with @IgnoredOnParcel must have a default value.

@Parcelize
class MyClass(
    val include: String,
    // Don't serialize this property
    @IgnoredOnParcel val ignore: String = "default"
): Parcelable {
    // Silence a warning
    @IgnoredOnParcel
    val computed: String = include + ignore
}

Use android.os.Parcel.writeValue for serializing a property

You can annotate a type with @RawValue to make Parcelize use Parcel.writeValue for that property.

@Parcelize
class MyClass(val external: @RawValue ExternalClass): Parcelable

This might fail at runtime if the value of the property is not natively supported by Android.

Parcelize might also require you to use this annotation when there is no other way to serialize the property.

Parcelize with sealed classes and sealed interfaces

Parcelize requires a class to parcelize to not be abstract. This limitation does not hold for sealed classes. When the @Parcelize annotation is used on a sealed class, it does not need to be repeated for the deriving classes.

@Parcelize
sealed class SealedClass: Parcelable {
    class A(val a: String): SealedClass()
    class B(val b: Int): SealedClass()
}

@Parcelize
class MyClass(val a: SealedClass.A, val b: SealedClass.B, val c: SealedClass): Parcelable

Setup Parcelize for Kotlin multiplatform

Prior to Kotlin 2.0, you could use Parcelize by aliasing Parcelize annotations with expect and actual:

// Common code
package example

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

expect interface MyParcelable

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

@MyParcelize
class MyClass(
    val x: String,
    @MyIgnoredOnParcel val y: String = ""
): MyParcelable

// Platform code
package example

actual typealias MyParcelize = kotlinx.parcelize.Parcelize
actual typealias MyParcelable = android.os.Parcelable
actual typealias MyIgnoredOnParcel = kotlinx.parcelize.IgnoredOnParcel

In Kotlin 2.0 and higher, aliasing annotations that trigger plugins is unsupported. To circumvent this, provide a new Parcelize annotation as the additionalAnnotation parameter to the plugin instead.

// Gradle build configuration
kotlin {
    androidTarget {
        compilerOptions {
            // ...
            freeCompilerArgs.addAll("-P", "plugin:org.jetbrains.kotlin.parcelize:additionalAnnotation=example.MyParcelize")
        }
    }
}

// Common code
package example

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.BINARY)
// No `expect` keyword here
annotation class MyParcelize()

expect interface MyParcelable

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

@MyParcelize
class MyClass(
    val x: String,
    @MyIgnoredOnParcel val y: String = ""
): MyParcelable

// Platform code
package example

// No typealias for MyParcelize here
actual typealias MyParcelable = android.os.Parcelable
actual typealias MyIgnoredOnParcel = kotlinx.parcelize.IgnoredOnParcel

Because the Parcel interface is only available on Android, Parcelize won't generate any code on other platforms, so any actual implementations there can be empty. It is also not possible to use any annotation that requires referencing the Parcel class, for example @WriteWith, in common code.

Feedback

If you encounter any issues with the kotlin-parcelize Gradle plugin, you can file a bug.