Migrating to Jetpack Compose

Stay organized with collections Save and categorize content based on your preferences.

1. Introduction

Compose and the View system can work together side by side.

In this codelab, you'll be migrating parts of the Sunflower's plant details screen to Compose. We created a copy of the project for you to try out migrating a realistic app to Compose.

By the end of the codelab, you'll be able to continue with the migration and convert the rest of Sunflower's screens if you wish.

For more support as you're walking through this codelab, check out the following code-along:

What you will learn

In this codelab, you will learn:

  • The different migration paths you can follow
  • How to incrementally migrate an app to Compose
  • How to add Compose to an existing screen built using Android views
  • How to use an Android View from inside Compose
  • How you can use your theme from the View system in Compose
  • How to test a screen with View system and Compose code

Prerequisites

What you will need

2. Plan your migration

Migrating to Compose depends on you and your team. There are many different ways to integrate Jetpack Compose into an existing Android app. Two common migration strategies are:

  • Develop a new screen entirely with Compose
  • Take an existing screen, and gradually migrate components of it.

Compose in new screens

A common approach when refactoring your app to a new technology is adopting it in new features you build for your app. In this case, new screens apply. If you need to build a new UI screen for your app, consider using Compose for it while the rest of the app might remain in the View system.

In this case, you'll be doing Compose interop at the edges of those migrated features.

Compose and Views together

Given a screen, you can have some parts migrated to Compose and others in the View system. For example, you could migrate a RecyclerView while leaving the rest of the screen in the View system.

Or vice-versa, use Compose as the outer layout and use some existing views that might not be available in Compose such as MapView or AdView.

Complete migration

Migrate whole fragments or screens to Compose one at a time. Simplest, but very coarse grained.

And in this codelab?

In this codelab, you'll be doing an incremental migration to Compose of the Sunflower's plant details screen having Compose and Views working together. After that, you'll know enough to continue with the migration if you wish.

3. Getting set up

Get the code

Get the codelab code from GitHub:

$ git clone https://github.com/googlecodelabs/android-compose-codelabs

Alternatively you can download the repository as a Zip file:

Running the sample app

The code you just downloaded contains code for all Compose codelabs available. To complete this codelab, open the MigrationCodelab project inside Android Studio.

In this codelab, you're going to migrate Sunflower's plant details screen to Compose. You can open the plant details screen by tapping in one of the plants available in the plant list screen.

bb6fcf50b2899894.png

Project setup

The project is built in multiple git branches:

  • main is the branch you checked out or downloaded. This is the codelab's starting point.
  • end contains the solution to this codelab.

We recommend that you start with the code in the main branch and follow the codelab step-by-step at your own pace.

During the codelab, you'll be presented with snippets of code that you'll need to add to the project. In some places, you'll also need to remove code that is explicitly mentioned in comments on the code snippets.

To get the end branch using git, use this command:

$ git clone -b end https://github.com/googlecodelabs/android-compose-codelabs

Or download the solution code from here:

Frequently asked questions

4. Compose in Sunflower

Compose is already added to the code you downloaded from the main branch. However, let's take a look at what's required to have it working.

If you open the app-level build.gradle (or project-level build.gradle) file, see how it imports the Compose dependencies and enables Android Studio to work with Compose by using the buildFeatures { compose true } flag.

app/build.gradle

android {
    ...
    kotlinOptions {
        jvmTarget = '1.8'
        useIR = true
    }
    buildFeatures {
        ...
        compose true
    }
    composeOptions {
        kotlinCompilerExtensionVersion rootProject.composeVersion
    }
}

dependencies {
    ...
    // Compose
    implementation "androidx.compose.runtime:runtime:$rootProject.composeVersion"
    implementation "androidx.compose.ui:ui:$rootProject.composeVersion"
    implementation "androidx.compose.foundation:foundation:$rootProject.composeVersion"
    implementation "androidx.compose.foundation:foundation-layout:$rootProject.composeVersion"
    implementation "androidx.compose.material:material:$rootProject.composeVersion"
    implementation "androidx.compose.runtime:runtime-livedata:$rootProject.composeVersion"
    implementation "androidx.compose.ui:ui-tooling:$rootProject.composeVersion"
    implementation "com.google.android.material:compose-theme-adapter:$rootProject.composeVersion"
    ...
}

The version of those dependencies are defined in the project-level build.gradle file.

5. Hello Compose!

In the plant details screen, we'll migrate the description of the plant to Compose while leaving the overall structure of the screen intact. Here, you'll be following the Compose and Views together migration strategy mentioned in the Plan your migration section.

Compose needs a host Activity or Fragment in order to render UI. In Sunflower, as all screens use fragments, you'll be using ComposeView: an Android View that can host Compose UI content using its setContent method.

Removing XML code

Let's start with the migration! Open fragment_plant_detail.xml and do the following:

  1. Switch to the Code view
  2. Remove the ConstraintLayout code and nested TextViews inside the NestedScrollView (the codelab will compare and reference the XML code when migrating individual items, having the code commented out will be useful)
  3. Add a ComposeView that will host Compose code instead with compose_view as view id

fragment_plant_detail.xml

<androidx.core.widget.NestedScrollView
    android:id="@+id/plant_detail_scrollview"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:clipToPadding="false"
    android:paddingBottom="@dimen/fab_bottom_padding"
    app:layout_behavior="@string/appbar_scrolling_view_behavior">

    // Step 2) Comment out ConstraintLayout and its children
    <androidx.constraintlayout.widget.ConstraintLayout
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:layout_margin="@dimen/margin_normal">

        <TextView
            android:id="@+id/plant_detail_name"
        ...
    
    </androidx.constraintlayout.widget.ConstraintLayout>
    // End Step 2) Comment out until here

    // Step 3) Add a ComposeView to host Compose code
    <androidx.compose.ui.platform.ComposeView
        android:id="@+id/compose_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

</androidx.core.widget.NestedScrollView>

Adding Compose code

At this point, you are ready to start migrating the plant details screen to Compose!

Throughout the codelab, you'll be adding Compose code to the PlantDetailDescription.kt file under the plantdetail folder. Open it and see how we have a placeholder "Hello Compose" text already available in the project.

PlantDetailDescription.kt

@Composable
fun PlantDetailDescription() {
    Surface {
        Text("Hello Compose")
    }  
}

Let's display this on the screen by calling this composable from the ComposeView we added in the previous step. Open PlantDetailFragment.kt.

As the screen is using data binding, you can directly access the composeView and call setContent to display Compose code on the screen. Call the PlantDetailDescription composable inside MaterialTheme as Sunflower uses material design.

PlantDetailFragment.kt

class PlantDetailFragment : Fragment() {
    // ...
    override fun onCreateView(...): View? {
        val binding = DataBindingUtil.inflate<FragmentPlantDetailBinding>(
            inflater, R.layout.fragment_plant_detail, container, false
        ).apply {
            // ...
            composeView.setContent {
                // You're in Compose world!
                MaterialTheme {
                    PlantDetailDescription()
                }
            }
        }
        // ...
    }
}

If you run the app, you can see "Hello Compose" is displayed on the screen.

66f3525ecf6669e0.png

6. Creating a Composable out of XML

Let's start by migrating the name of the plant. More exactly, the TextView with id @+id/plant_detail_name you removed in fragment_plant_detail.xml. Here's the XML code:

<TextView
    android:id="@+id/plant_detail_name"
    ...
    android:layout_marginStart="@dimen/margin_small"
    android:layout_marginEnd="@dimen/margin_small"
    android:gravity="center_horizontal"
    android:text="@{viewModel.plant.name}"
    android:textAppearance="?attr/textAppearanceHeadline5"
    ... />

See how it has a textAppearanceHeadline5 style, has a horizontal margin of 8.dp and it's centered horizontally on the screen. However, the title to be displayed is observed from a LiveData exposed by PlantDetailViewModel that comes from the repository layer.

As observing a LiveData is covered later, let's assume we have the name available and is passed as a parameter to a new PlantName composable that we create in the PlantDetailDescription.kt file. This composable will be called from the PlantDetailDescription composable later.

PlantDetailDescription.kt

@Composable
private fun PlantName(name: String) {
    Text(
        text = name,
        style = MaterialTheme.typography.h5,
        modifier = Modifier
            .fillMaxWidth()
            .padding(horizontal = dimensionResource(R.dimen.margin_small))
            .wrapContentWidth(Alignment.CenterHorizontally)
    )
}

@Preview
@Composable
private fun PlantNamePreview() {
    MaterialTheme {
        PlantName("Apple")
    }
}

With preview:

d09fe886b98bde91.png

Where:

  • Text's style is MaterialTheme.typography.h5 that maps to the textAppearanceHeadline5 from the XML code.
  • The modifiers decorate the Text to adjust it to look like the XML version:
  • fillMaxWidth modifier corresponds to the android:layout_width="match_parent" in XML code.
  • horizontal padding of margin_small that is a value from the View system using the dimensionResource helper function.
  • wrapContentWidth to align the Text horizontally.

7. ViewModels and LiveData

Now, let's wire up the title to the screen. To do that, you'll need to load the data using the PlantDetailViewModel. For that, Compose comes with integrations for ViewModel and LiveData.

ViewModels

As an instance of the PlantDetailViewModel is used in the Fragment, we could pass it as a parameter to PlantDetailDescription and that'd be it.

Open the PlantDetailDescription.kt file and add the PlantDetailViewModel parameter to PlantDetailDescription:

PlantDetailDescription.kt

@Composable
fun PlantDetailDescription(plantDetailViewModel: PlantDetailViewModel) {
    ...
}

Now, pass the instance of the ViewModel when calling this composable from the fragment:

PlantDetailFragment.kt

class PlantDetailFragment : Fragment() {
    ...
    override fun onCreateView(...): View? {
        ...
        composeView.setContent {
            MaterialTheme {
                PlantDetailDescription(plantDetailViewModel)
            }
        }
    }
}

LiveData

With this, you already have access to the PlantDetailViewModel's LiveData<Plant> field to get the plant's name.

To observe LiveData from a composable, use the LiveData.observeAsState() function.

As values emitted by the LiveData can be null, you'd need to wrap it's usage in a null check. Because of that and for reusability purposes, it's a good pattern to split the LiveData consumption and listening in different composables. Thus, create a new composable called PlantDetailContent that will display Plant information.

Given the above, this is how the PlantDetailDescription.kt file looks like after adding the LiveData observation.

PlantDetailDescription.kt

@Composable
fun PlantDetailDescription(plantDetailViewModel: PlantDetailViewModel) {
    // Observes values coming from the VM's LiveData<Plant> field
    val plant by plantDetailViewModel.plant.observeAsState()

    // If plant is not null, display the content
    plant?.let {
        PlantDetailContent(it)
    }
}

@Composable
fun PlantDetailContent(plant: Plant) {
    PlantName(plant.name)
}

@Preview
@Composable
private fun PlantDetailContentPreview() {
    val plant = Plant("id", "Apple", "description", 3, 30, "")
    MaterialTheme {
        PlantDetailContent(plant)
    }
}

With same preview as PlantNamePreview since PlantDetailContent just calls PlantName at the moment:

3e47e682cf518c71.png

Now, you've wired up the ViewModel all the way to display a plant name in Compose. In the next few sections, you'll build the rest of the composables and wire them up to the ViewModel in a similar way.

8. More XML code migration

Now, it's easier to complete what's missing in our UI: the watering info and plant description. Following the same looking at the XML code approach you did before, you can already migrate the rest of the screen.

The watering info XML code you removed before from fragment_plant_detail.xml consists of two TextViews with ids plant_watering_header and plant_watering.

<TextView
    android:id="@+id/plant_watering_header"
    ...
    android:layout_marginStart="@dimen/margin_small"
    android:layout_marginTop="@dimen/margin_normal"
    android:layout_marginEnd="@dimen/margin_small"
    android:gravity="center_horizontal"
    android:text="@string/watering_needs_prefix"
    android:textColor="?attr/colorAccent"
    android:textStyle="bold"
    ... />

<TextView
    android:id="@+id/plant_watering"
    ...
    android:layout_marginStart="@dimen/margin_small"
    android:layout_marginEnd="@dimen/margin_small"
    android:gravity="center_horizontal"
    app:wateringText="@{viewModel.plant.wateringInterval}"
    .../>

Similar to what you did before, create a new composable called PlantWatering and add Texts to display the watering information on the screen:

PlantDetailDescription.kt

@OptIn(ExperimentalComposeUiApi::class)
@Composable
private fun PlantWatering(wateringInterval: Int) {
    Column(Modifier.fillMaxWidth()) {
        // Same modifier used by both Texts
        val centerWithPaddingModifier = Modifier
            .padding(horizontal = dimensionResource(R.dimen.margin_small))
            .align(Alignment.CenterHorizontally)

        val normalPadding = dimensionResource(R.dimen.margin_normal)

        Text(
            text = stringResource(R.string.watering_needs_prefix),
            color = MaterialTheme.colors.primaryVariant,
            fontWeight = FontWeight.Bold,
            modifier = centerWithPaddingModifier.padding(top = normalPadding)
        )

        val wateringIntervalText = pluralStringResource(
            R.plurals.watering_needs_suffix, wateringInterval, wateringInterval
        )
        Text(
            text = wateringIntervalText,
            modifier = centerWithPaddingModifier.padding(bottom = normalPadding)
        )
    }
}

@Preview
@Composable
private fun PlantWateringPreview() {
    MaterialTheme {
        PlantWatering(7)
    }
}

With preview:

6f6c17085801a518.png

Some things to notice:

  • As the horizontal padding and align decoration is shared by the Text composables, you can reuse the Modifier by assigning it to a local variable (i.e. centerWithPaddingModifier). Since modifiers are regular Kotlin objects, you can do that.
  • Compose's MaterialTheme doesn't have an exact match to the colorAccent used in plant_watering_header. For now, let's use MaterialTheme.colors.primaryVariant that you'll improve in the interop theming section.
  • In Compose 1. 2.1, using pluralStringResource requires opting in to ExperimentalComposeUiApi. In a future version of Compose this may no longer be needed.

Let's connect all the pieces together and call PlantWatering from the PlantDetailContent as well. The ConstraintLayout XML code we removed at the beginning had a margin of 16.dp that we need to include in our Compose code.

<androidx.constraintlayout.widget.ConstraintLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:layout_margin="@dimen/margin_normal">

In PlantDetailContent, create a Column to display the name and watering info together and have that as padding. Also, so that the background color and the text colors used are appropriate, add a Surface that will handle that.

PlantDetailDescription.kt

@Composable
fun PlantDetailContent(plant: Plant) {
    Surface {
        Column(Modifier.padding(dimensionResource(R.dimen.margin_normal))) {
            PlantName(plant.name)
            PlantWatering(plant.wateringInterval)
        }
    }
}

If you refresh the preview, you'll see this:

56626a7118ce075c.png

9. Views in Compose code

Now, let's migrate the plant description. The code in fragment_plant_detail.xml had a TextView with app:renderHtml="@{viewModel.plant.description}" to tell the XML what text to display on the screen. renderHtml is a binding adapter that you can find in the PlantDetailBindingAdapters.kt file. The implementation uses HtmlCompat.fromHtml to set the text on the TextView!

However, Compose doesn't have support for Spanned classes nor displaying HTML formatted text at the moment. Thus, we need to use a TextView from the View system in the Compose code to bypass this limitation.

As Compose is not able to render HTML code yet, you'll create a TextView programmatically to do exactly that using the AndroidView API.

AndroidView takes a View as a parameter and gives you a callback for when the View has been inflated.

Let's do this by creating a new PlantDescription composable. This composable calls AndroidView with the TextView we just remembered in a lambda. In the factory callback, initialize a TextView that reacts to HTML interactions using the given Context. And in the update callback, set the text with a remembered HTML formatted description.

PlantDetailDescription.kt

@Composable
private fun PlantDescription(description: String) {
    // Remembers the HTML formatted description. Re-executes on a new description
    val htmlDescription = remember(description) {
        HtmlCompat.fromHtml(description, HtmlCompat.FROM_HTML_MODE_COMPACT)
    }

    // Displays the TextView on the screen and updates with the HTML description when inflated
    // Updates to htmlDescription will make AndroidView recompose and update the text
    AndroidView(
        factory = { context ->
            TextView(context).apply {
                movementMethod = LinkMovementMethod.getInstance()
            }
        },
        update = {
            it.text = htmlDescription
        }
    )
}

@Preview
@Composable
private fun PlantDescriptionPreview() {
    MaterialTheme {
        PlantDescription("HTML<br><br>description")
    }
}

Preview:

deea1d191e9087b4.png

Notice that htmlDescription remembers the HTML description for a given description passed as a parameter. If the description parameter changes, the htmlDescription code inside remember will execute again.

Similarly, the AndroidView update callback will recompose if htmlDescription changes. Any state read inside the callback causes a recomposition.

Let's add PlantDescription to the PlantDetailContent composable and change preview code to display a HTML description too:

PlantDetailDescription.kt

@Composable
fun PlantDetailContent(plant: Plant) {
    Surface {
        Column(Modifier.padding(dimensionResource(R.dimen.margin_normal))) {
            PlantName(plant.name)
            PlantWatering(plant.wateringInterval)
            PlantDescription(plant.description)
        }
    }
}

@Preview
@Composable
private fun PlantDetailContentPreview() {
    val plant = Plant("id", "Apple", "HTML<br><br>description", 3, 30, "")
    MaterialTheme {
        PlantDetailContent(plant)
    }
}

With preview:

7843a8d6c781c244.png

At this point, you've migrated all the content inside the original ConstraintLayout to Compose. You can run the app to check that it's working as expected.

c7021c18eb8b4d4e.gif

10. ViewCompositionStrategy

Compose disposes of the Composition whenever the ComposeView becomes detached from a window. This is undesirable when ComposeView is used in fragments for multiple reasons:

  • The Composition must follow the fragment's view lifecycle for Compose UI View types to save state, and
  • to keep the Compose UI elements on the screen when transitions, or window transitions happen. During transitions, the ComposeView itself is still visible even after it is detached from the window.

You can manually call the AbstractComposeView.disposeComposition method to dispose of the Composition manually. Alternatively, for disposing Compositions automatically when they're no longer needed, set a different strategy or create your own by calling the setViewCompositionStrategy method.

Use the DisposeOnViewTreeLifecycleDestroyed strategy to dispose of the Composition when the LifecycleOwner of the fragment is destroyed.

As PlantDetailFragment has enter and exit transitions (check nav_garden.xml for more info), and we'll use View types inside Compose later, we need to make sure the ComposeView uses the DisposeOnViewTreeLifecycleDestroyed strategy. Nonetheless, it's a good practice to always set this strategy when using ComposeView in fragments.

PlantDetailFragment.kt

import androidx.compose.ui.platform.ViewCompositionStrategy
...

class PlantDetailFragment : Fragment() {
    ...
    override fun onCreateView(...): View? {
        val binding = DataBindingUtil.inflate<FragmentPlantDetailBinding>(
            inflater, R.layout.fragment_plant_detail, container, false
        ).apply {
            ...
            composeView.apply {
                // Dispose the Composition when the view's LifecycleOwner
                // is destroyed
                setViewCompositionStrategy(
                    ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed
                )
                setContent {
                    MaterialTheme {
                        PlantDetailDescription(plantDetailViewModel)
                    }
                }
            }
        }
        ...
    }
}

11. Interop theming

We have the text content of plant details migrated to Compose. However, you might have noticed that Compose is not using the right theme colors. It's using purple in the plant name when it should be using green.

At this early migration stage, you might want Compose to inherit the themes available in the View system instead of rewriting your own Material theme in Compose from scratch. The Material themes work perfectly with all the Material design components that comes with Compose.

To reuse your View system Material Design Components (MDC) theme in Compose, you can use the compose-theme-adapter. The MdcTheme function will automatically read the host context's MDC theme and pass them to MaterialTheme on your behalf for both light and dark themes. Even though you just need the theme colors for this codelab, the library also reads the View system's shapes and typography.

The library is already included in the app/build.gradle file as follows:

...
dependencies {
    ...
    implementation "com.google.android.material:compose-theme-adapter:$rootProject.composeVersion"
    ...
}

To use this, replace MaterialTheme usages for MdcTheme. For example, in PlantDetailFragment:

PlantDetailFragment.kt

class PlantDetailFragment : Fragment() {
    ...
    composeView.apply {
        ...
        setContent {
            MdcTheme {
                PlantDetailDescription(plantDetailViewModel)
            }
        }
    }
}

And all the preview composables in the PlantDetailDescription.kt file:

PlantDetailDescription.kt

@Preview
@Composable
private fun PlantDetailContentPreview() {
    val plant = Plant("id", "Apple", "HTML<br><br>description", 3, 30, "")
    MdcTheme {
        PlantDetailContent(plant)
    }
}

@Preview
@Composable
private fun PlantNamePreview() {
    MdcTheme {
        PlantName("Apple")
    }
}

@Preview
@Composable
private fun PlantWateringPreview() {
    MdcTheme {
        PlantWatering(7)
    }
}

@Preview
@Composable
private fun PlantDescriptionPreview() {
    MdcTheme {
        PlantDescription("HTML<br><br>description")
    }
}

As you can see in the preview, MdcTheme is picking up the colors from the theme in styles.xml file.

886d7eaea611f4eb.png

You can also preview the UI in dark theme by creating a new function and passing Configuration.UI_MODE_NIGHT_YES to the uiMode of the preview:

import android.content.res.Configuration
...

@Preview(uiMode = Configuration.UI_MODE_NIGHT_YES)
@Composable
private fun PlantDetailContentDarkPreview() {
    val plant = Plant("id", "Apple", "HTML<br><br>description", 3, 30, "")
    MdcTheme {
        PlantDetailContent(plant)
    }
}

With preview:

cfe11c109ff19eeb.png

If you run the app, it behaves exactly the same as before the migration in both light and dark theme:

c99216fc77699dd7.gif

12. Testing

After migrating parts of the plant detail screen to Compose, testing is critical to make sure you haven't broken anything.

In Sunflower, PlantDetailFragmentTest located in the androidTest folder tests some functionality of the app. Open the file and take a look at the current code:

  • testPlantName checks for the name of the plant on the screen
  • testShareTextIntent checks that the right intent is triggered after tapping on the share button

When an activity or fragment uses compose, instead of using ActivityScenarioRule, you need to use createAndroidComposeRule that integrates ActivityScenarioRule with a ComposeTestRule that lets you test Compose code.

In PlantDetailFragmentTest, replace the usage ActivityScenarioRule with createAndroidComposeRule. When the activity rule is needed to configure the test, use the activityRule attribute from createAndroidComposeRule as follows:

@RunWith(AndroidJUnit4::class)
class PlantDetailFragmentTest {

    @Rule
    @JvmField
    val composeTestRule = createAndroidComposeRule<GardenActivity>()
   
    ...

    @Before
    fun jumpToPlantDetailFragment() {
        populateDatabase()

        composeTestRule.activityRule.scenario.onActivity { gardenActivity ->
            activity = gardenActivity

            val bundle = Bundle().apply { putString("plantId", "malus-pumila") }
            findNavController(activity, R.id.nav_host).navigate(R.id.plant_detail_fragment, bundle)
        }
    }

    ...
}

If you run the tests, testPlantName will fail! testPlantName checks for a TextView to be on the screen. However, you migrated that part of the UI to Compose. Thus, you need to use Compose assertions instead:

@Test
fun testPlantName() {
    composeTestRule.onNodeWithText("Apple").assertIsDisplayed()
}

If you run the tests, you'll see all of them pass.

dd59138fac1740e4.png

13. Congratulations

Congratulations, you've successfully completed this codelab!

The compose branch of the original Sunflower github project completely migrates the plant details screen to Compose. Apart from what you've done in this codelab, it also simulates the behavior of the CollapsingToolbarLayout. This involves:

  • Loading images with Compose
  • Animations
  • Better dimensions handling
  • And more!

What's next?

Check out the other codelabs on the Compose pathway:

Further reading