The Android Developer Challenge is back! Submit your idea before December 2.

Use Android Studio with Jetpack Compose

Jetpack Compose is a modern toolkit for building native Android UI. It's based on the declarative programming model, so you can simply describe what your UI should look like, and Compose takes care of the rest—as app state changes, your UI automatically updates. Because it’s built on Kotlin, it's fully interoperable with the Java programming language and has direct access to all of the Android and Jetpack APIs. It’s compatible with the existing UI toolkit, so you can mix and match classic and new views, and it’s designed with Material and animations from the start.

For the best experience developing with Jetpack Compose, you should download the latest version of Android Studio Preview. That’s because when you use Android Studio to develop your app with Jetpack Compose, you can benefit from smart editor features, such as New Project templates and the ability to immediately preview your Compose UI.

Get Android Studio

After you've installed Android Studio, follow the instructions below to try a Jetpack Compose sample app, create a new Jetpack Compose app project, or add support for Jetpack Compose to an existing app project.

Try a Jetpack sample app

After you’ve the latest version of Android Studio running, the fastest way to experiment with the capabilities of Jetpack Compose is by trying the "Jetnews" sample app hosted on GitHub. To import the sample app project from Android Studio, proceed as follows:

  1. If you’re in the Welcome to Android Studio window, select Import an Android code sample. If you already have an Android Studio project open, select File > New > Import Sample from the menu bar.
  2. In the search bar near the top of the Browse Samples wizard, type "Jetnews".
  3. Select the Jetnews sample app from the search results and click Next.
  4. Either change the Application name and Project location or keep the default values.
  5. Click Finish.

Android Studio downloads the sample app to the path you specified and opens the project. You can then inspect MainActivity.kt to see examples of crossfade animation, custom components, using typography, and displaying light and dark colors in the in-IDE preview.

Create a new app with support for Jetpack Compose

If you want to start a new project that includes support for Jetpack Compose by default, Android Studio includes new project templates to help you get started. To create a new project that include Jetpack Compose, proceed as follows:

  1. If you’re in the Welcome to Android Studio window, click Start a new Android Studio project. If you already have an Android Studio project open, select File > New > New Project from the menu bar.
  2. In the Select a Project Template window, select Empty Compose Activity and click Next.
  3. In the Configure your project window, do the following:
    1. Set the Name, Package name, and Save location as you normally would.
    2. Note that, in the Language dropdown menu, Kotlin is the only available option because Jetpack Compose works only with classes written in Kotlin.
    3. In the Minimum API level dropdown menu, select API level 21 or higher.
  4. Click Finish.

Now you're ready to start developing an app using Jetpack Compose. To help you get started and learn about what you can do with the toolkit, try the Jetpack Compose tutorial.

Add Jetpack Compose to an existing project

If you want to use Jetpack Compose in an existing project, you’ll need to configure your project with required settings and dependencies.

Configure Gradle

You need to set your app’s minimum API level to 21 or higher and enable Jetpack Compose in your app's build.gradle file, as shown below:

android {
    defaultConfig {
        ...
        minSdkVersion 21
    }

    buildFeatures {
        // Enables Jetpack Compose for this module
        compose true
    }
    ...

    // Set both the Java and Kotlin compilers to target Java 8.

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Use the experimental Kotlin-Gradle plugin

Jetpack Compose currently requires an experimental version of the Kotlin-Gradle plugin. To include this plugin in your app, include the following in your project’s build.gradle file:

buildscript {
    repositories {
        google()
        jcenter()
        // To download the required version of the Kotlin-Gradle plugin,
        // add the following repository.
        maven { url 'https://dl.bintray.com/kotlin/kotlin-eap' }
    ...
    dependencies {
        classpath 'com.android.tools.build:gradle:4.0.0-alpha01'
        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.3.60-eap-25'
    }
}

allprojects {
    repositories {
        google()
        jcenter()
        maven { url 'https://dl.bintray.com/kotlin/kotlin-eap' }
    }
}

Add Jetpack Compose toolkit dependencies

Include Jetpack Compose toolkit dependencies in your app’s build.gradle file, as shown below:

dependencies {
    // You also need to include the following Compose toolkit dependencies.
    implementation 'androidx.ui:ui-tooling:0.1.0-dev02'
    implementation 'androidx.ui:ui-layout:0.1.0-dev02'
    implementation 'androidx.ui:ui-material:0.1.0-dev02'
    ...
}

Use live previews

Live previews is an Android Studio feature that allows you to test and compare your app's composable functions across various orientations, font sizes, and themes—without having to deploy your app.

Live previews, each using a different width, theme, and font scaling.

Figure 1. Using different dimensions, themes, and font scaling to preview composable functions

As shown in figure 1, you can have multiple previews of a certain composable function, each with a different width and height restriction, font scaling, or theme. As you develop your app, change resources, or colors, your live previews update to help you review your changes. Additionally, you can click on elements in the preview to quickly navigate to the composable function for that element in the code editor.

Create a basic live preview

Below is an example of a composable function, called TutorialPreviewTemplate().

@Composable
fun TutorialPreviewTemplate(
    colors: MaterialColors = lightThemeColors,
    typography: MaterialTypography = themeTypography
) {
    val context = +ambient(ContextAmbient)
    val previewPosts = getPostsWithImagesLoaded(posts.subList(1, 2), context.resources)
    val post = previewPosts[0]
    MaterialTheme(colors = colors, typography = typography) {
        Surface {
            PostCardTop(post)
        }
    }
}

To create a live preview, create a new composable function that takes no parameters and includes a @Preview annotation before @Composable, as shown below:

/// This is the original composable function.
@Composable
fun TutorialPreviewTemplate( ... ) { ... }

// A new composable function that applies the @Preview annotation and does not
// take any parameters.
@Preview
@Composable
fun TutorialPreview() {
    // Call the composable function that you would like to
    // create a live preview for.
    TutorialPreviewTemplate()
}

When you create or modify a live preview you need to rebuild your project to see the changes. To rebuild your project, either click Build in the banner at the top of the editor, or select Build > Make Project from the menu bar.

Basic live preview of a composable function.

Figure 2. A basic live preview of a composable function in Android Studio

You can create multiple live previews, which appear side-by-side in the IDE's Preview window, as shown below. This is useful for comparing how your composable functions behave when, for example, they are given different arguments.

/// This is the original composable function.
@Composable
fun TutorialPreviewTemplate( ... ) { ... }

@Preview
@Composable
fun TutorialPreview() { ... }

// This live preview uses the app's dark theme.
@Preview
@Composable
fun TutorialPreviewDark() {
    // Although you can't pass arguments to the live preview function itself,
    // you can pass arguments to the composable function that it calls.
    TutorialPreviewTemplate(colors = darkThemeColors)
}

Live previews using different themes.

Figure 3. Two live previews of a composable function, each using different themes

Pass arguments to the @Preview annotation

The @Preview annotation provides certain parameters that you can use to change how the IDE renders a composable function in the Preview window. For example, as shown below, you can name a live preview by passing a string, which can help you better identify a live preview.

// Pass a name for the preview to easily identify it in the Preview window.
@Preview("Default colors")
@Composable
fun TutorialPreview() {
    TutorialPreviewTemplate()
}

@Preview("Dark colors")
@Composable
fun TutorialPreviewDark() {
    TutorialPreviewTemplate(colors = darkThemeColors)
}

Additional @Preview parameters you can pass arguments for are as follows:

  • widthDp: The max width, measured in density-independent pixels (dp), that the IDE can use when rendering the live preview. This is useful when you want to preview your composable function on limited screen sizes.
  • heightDp: The max height, measured in dp, that the IDE can use when rendering the live preview. This is useful when you want to preview your composable function on limited screen sizes.
  • fontScale: The scaling factor, relative to the base density scaling (1f), for fonts. This is useful for when you want to test your composable function for various user font size preferences.

The example below changes the default scaling factor and max height for a live preview.

@Preview("Font scaling 1.5, height 300", fontScale = 1.5f, heightDp = 300)
@Composable
fun TutorialPreviewFontscale() {
    TutorialPreviewTemplate()
}

A live preview using a modified font scaling and max height.

Figure 4. A live preview using a modified font scaling and max height