Google is committed to advancing racial equity for Black communities. See how.

Compose

Define your UI programmatically with composable functions that describe its shape and data dependencies.
Latest Update Current Stable Release Next Release Candidate Beta Release Alpha Release
September 16, 2020 - - - 1.0.0-alpha03

Structure

Compose is combination of 7 Maven Group Ids within androidx. Each Group contains a targeted subset of functionality, each with it's own set of release notes.

This table explains the groups and links to each set of release notes.

GroupDescription
composeDefine your UI programmatically with composable functions that describe its shape and data dependencies.
compose.animationBuild animations in their Jetpack Compose applications to enrich the user experience.
compose.foundationWrite Jetpack Compose applications with ready to use building blocks and extend foundation to build your own design system pieces.
compose.materialBuild Jetpack Compose UIs with ready to use Material Design Components. This is the higher level entry point of Compose, designed to provide components that match those described at www.material.io.
compose.runtimeFundamental building blocks of Compose's programming model and state management, and core runtime for the Compose Compiler Plugin to target.
compose.uiFundamental components of compose UI needed to interact with the device, including layout, drawing, and input.
uiWorks with the Jetpack Compose library.

Declaring dependencies

To add a dependency on Compose, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerVersion "1.4.0"
        kotlinCompilerExtensionVersion "1.0.0-alpha03"
    }
}

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
    kotlinOptions {
        jvmTarget = "1.8"
        freeCompilerArgs += ["-Xallow-jvm-ir-dependencies", "-Xskip-prerelease-check"]
    }
}

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.0.0

Version 1.0.0-alpha03

September 16, 2020

androidx.compose:compose-compiler:1.0.0-alpha03 is released. Version 1.0.0-alpha03 contains these commits.

Version 1.0.0-alpha02

September 2, 2020

androidx.compose:compose-compiler:1.0.0-alpha02 is released with no changes since 1.0.0-alpha01. Version 1.0.0-alpha02 contains these commits.

Version 1.0.0-alpha01

August 26, 2020

androidx.compose:compose-compiler:1.0.0-alpha01 is released. Version 1.0.0-alpha01 contains these commits.

Version 0.1.0-dev

Version 0.1.0-dev17

August 19, 2020

androidx.compose:compose-compiler:0.1.0-dev17 is released. Version 0.1.0-dev17 contains these commits.

Version 0.1.0-dev16

August 5, 2020

androidx.compose:compose-compiler:0.1.0-dev16 is released. Version 0.1.0-dev16 contains these commits.

Most Jetpack Compose packages have been refactored, according to the table below.

Jetpack Compose Package Refactoring

Old Package Name New Package Name
androidx.animation androidx.compose.animation.core
androidx.ui.autofill androidx.compose.ui.autofill
androidx.compose androidx.compose.runtime
androidx.compose.dispatch androidx.compose.runtime.dispatch
androidx.ui.animation androidx.compose.animation
androidx.ui.core androidx.compose.ui
androidx.compose.ui.unit
androidx.compose.ui.graphics
androidx.ui.foundation androidx.compose.foundation
androidx.ui.geometry androidx.compose.ui.geometry
androidx.ui.graphics androidx.compose.ui.graphics
androidx.ui.input androidx.compose.ui.text.input
androidx.ui.intl androidx.compose.ui.text.intl
androidx.ui.layout androidx.compose.foundation.layout
androidx.ui.livedata androidx.compose.runtime.livedata
androidx.ui.material androidx.compose.material
androidx.ui.material.icons androidx.compose.material.icons
androidx.ui.rxjava2 androidx.compose.runtime.rxjava2
androidx.ui.savedinstancestate androidx.compose.runtime.savedinstancestate
androidx.ui.node androidx.compose.ui.node
androidx.compose.ui.input.pointer
androidx.ui.platform androidx.compose.ui.platform
androidx.ui.res androidx.compose.ui.res
androidx.ui.semantics androidx.compose.ui.semantics
androidx.ui.testutils androidx.compose.ui.input.pointer
androidx.ui.text androidx.compose.foundation.text
androidx.compose.ui.text
androidx.ui.text.platform androidx.compose.ui.text.android
androidx.compose.ui.platform
androidx.ui.unit androidx.compose.ui.unit
androidx.ui.util androidx.compose.ui.util
androidx.ui.viewinterop androidx.compose.ui.viewinterop
androidx.ui.viewmodel androidx.compose.ui.viewinterop
Not Yet Refactored (no changes)
androidx.ui.test
androidx.ui.tooling

If you are using Android Studio, you can replace your import statements with the code snippet below and use the Optimize Imports button in Android Studio. For any cases that Android Studio doesn't cover, please reference the package list above.

  import androidx.compose.runtime.*
  import androidx.compose.animation.*
  import androidx.compose.animation.core.*
  import androidx.compose.foundation.*
  import androidx.compose.foundation.gestures.*
  import androidx.compose.foundation.layout.*
  import androidx.compose.foundation.lazy.*
  import androidx.compose.foundation.shape.*
  import androidx.compose.material.*
  import androidx.compose.material.icons.*
  import androidx.compose.material.icons.filled.*
  import androidx.compose.ui.*
  import androidx.compose.ui.geometry.*
  import androidx.compose.ui.draw.*
  import androidx.compose.ui.graphics.*
  import androidx.compose.ui.graphics.drawscope.*
  import androidx.compose.ui.graphics.painter.*
  import androidx.compose.ui.graphics.vector.*
  import androidx.compose.ui.layout.*
  import androidx.compose.ui.platform.*
  import androidx.compose.ui.res.*
  import androidx.compose.ui.text.*
  import androidx.compose.ui.text.font.*
  import androidx.compose.ui.text.style.*
  import androidx.compose.ui.unit.*
  import androidx.compose.ui.util.*
  import androidx.compose.ui.viewinterop.*
  import androidx.ui.tooling.preview.*

Version 0.1.0-dev15

July 22, 2020

androidx.compose:compose-compiler:0.1.0-dev15 is released. Version 0.1.0-dev15 contains these commits.

Most Jetpack Compose artifacts have been refactored, according to the table below.

Please note, in this release only the artifact names have been refactored. In future releases, the package names will be updated to follow its new artifact name.

Jetpack Compose Artifact Refactoring

Old Artifact New Artifact
androidx.compose:compose-dispatch androidx.compose.runtime:runtime-dispatch
androidx.compose:compose-runtime androidx.compose.runtime:runtime
androidx.ui:ui-animation androidx.compose.animation:animation
androidx.ui:ui-animation-core androidx.compose.animation:animation-core
androidx.ui:ui-core androidx.compose.ui:ui
androidx.ui:ui-foundation androidx.compose.foundation:foundation
androidx.ui:ui-geometry androidx.compose.ui:ui-geometry
androidx.ui:ui-graphics androidx.compose.ui:ui-graphics
androidx.ui:ui-layout androidx.compose.foundation:foundation-layout
androidx.ui:ui-livedata androidx.compose.runtime:runtime-livedata
androidx.ui:ui-material androidx.compose.material:material
androidx.ui:ui-material-icons-core androidx.compose.material:material-icons-core
androidx.ui:ui-material-icons-extended androidx.compose.material:material-icons-extended
androidx.ui:ui-rxjava2 androidx.compose.runtime:runtime-rxjava2
androidx.ui:ui-saved-instance-state androidx.compose.runtime:runtime-saved-instance-state
androidx.ui:ui-text androidx.compose.foundation:foundation-text
androidx.ui:ui-text-android androidx.compose.ui:ui-text-android
androidx.ui:ui-text-core androidx.compose.ui:ui-text
androidx.ui:ui-unit androidx.compose.ui:ui-unit
androidx.ui:ui-util androidx.compose.ui:ui-util
Not Yet Refactored (no changes)
androidx.compose:compose-compiler
androidx.ui:ui-test
androidx.ui:ui-tooling

Dependencies Update

  • To use the 0.1.0-dev15 version of Compose, you will need to update your dependencies according to the new code snippets shown above in Declaring dependencies.

Version 0.1.0-dev14

June 24, 2020

androidx.compose:compose-compiler:0.1.0-dev14 and androidx.compose:compose-runtime:0.1.0-dev14 are released. Version 0.1.0-dev14 contains these commits.

API Changes

  • The Recompose composable is no longer a useful abstraction. Most recomposition should happen as a result of MutableState assignments. For anything beyond that, it is recommended that you use the invalidate function to trigger a recomposition of the current scope. (Ifc992)
  • Observe is no longer a useful abstraction. If you need to replicate it, its implementation can be replicated by just creating a composable function which executes a composable lambda parameter. For example, @Composable fun Observe(body: @Composable () -> Unit) = body() (I40d37)
  • @Direct was deprecated in favor of @ComposableContract(restartable=false) (If4708)

Bug Fixes

  • androidx.ui.foundation.TextFieldValue and androidx.ui.input.EditorValue are deprecated. TextField, FilledTextField and CoreTextField composables that uses that type is also deprecated. Please use androidx.ui.input.TextFieldValue instead (I4066d, b/155211005)

External Contribution

  • Deprecated Flow<T>.collectAsState() with no initial value. Use StateFlow<T> or pass an explicit initial value instead. (I63f98, b/157674865).
    • Thanks to Zach Klippenstein from Square for contributing the following change!

Version 0.1.0-dev13

June 10, 2020

androidx.compose:compose-compiler:0.1.0-dev13 and androidx.compose:compose-runtime:0.1.0-dev13 are released. Version 0.1.0-dev13 contains these commits.

Known Issues

  • When the application depends on androidx.core:core-ktx:1.2.0, and a FontFamily with multiple fonts / font weights is used, font selection will render in regular font weight. We will be working on this issue, and currently the workaround is to use androidx.core:core-ktx:1.2.0-alpha01 or androidx.core:core-ktx:1.1.0.

Version 0.1.0-dev12

May 27, 2020

androidx.compose:compose-compiler:0.1.0-dev12 and androidx.compose:compose-runtime:0.1.0-dev12 are released. Version 0.1.0-dev12 contains these commits.

API Changes

  • Changes the code generation strategy of Compose’s compiler. Prior to the change, the compose compiler would transform calls to composable functions. With this change, we now transform the body of a composable function and leave the callsite unaltered (mostly).

    This means that most of the logic communicating with the compose runtime happens at the start of the function body, instead of at the callsite.

    This should be a source-compatible change for all usage of compose. Most users of compose should not have to update any code as a result of this change.

    In order to support this work, the JVM signature of all composable functions has changed. A Composable function accepting a single parameter is transformed into a function accepting 3 parameters, the additional parameters are the Composer, a ‘key’ integer. a bitmask integer used to propagate metadata through calls.

    Compose now also transforms default arguments to a composable function. It does this without introducing an additional synthetic default overload of the function itself, so this change will result in fewer functions being defined.

    Known intentional behavioral changes resulting from this:

    1. Some calls will skip where they wouldn’t have previously
    2. Composable expressions in default argument expressions are now correctly subscribed to and handled

    This work included some optimizations:

    1. The result of comparisons of parameters are propagated through the call graph to other composable functions. This will result in fewer comparisons at runtime, reduces the slot table size, as well as more skipping of composable functions that were previously not skipped
    2. Parameters which are determined to be “static” at compile time are no longer compared or stored in the runtime. This reduces the number of comparisons and reduces slot table size.
    3. Control flow structure of the body of functions is used to minimize the number of groups that are generated. This reduces slot table size and results in less work for the runtime
    4. Unused dispatch and receiver parameters to functions are not included in determining skippability of the function if they are not used inside of the body of the function.

    Most breaking changes were for APIs that the compiler targets directly, and typical use of compose will not be affected:

    1. Composer::startExpr was removed
    2. Composer::endExpr was removed
    3. Composer::call was deprecated
    4. The non-varargs overloads of key have been removed. Use the vararg version going forward.
    5. The Pivotal annotation was deprecated. Use key as a replacement.
    6. ScopeUpdateScope::updateScope was changed to expect a Function3 instead of Function1
    7. restartableFunction and restartableFunctionN were updated to include additional compile time parameters

    (I60756, b/143464846)

  • Added an adapter for the recently introduced StateFlow which allows as to pre-populate the initial value so the returned State is non-nullable (I61dd8, b/156233789)

@Model annotation is now deprecated

  • @Model annotation is now deprecated. Use state and mutableStateOf as alternatives. This deprecation decision was reached after much careful discussion.

    Justification

    Rationale includes but is not limited to:

    • Reduces API surface area and concepts we need to teach
    • More closely aligns with other comparable toolkits (Swift UI, React, Flutter)
    • Reversible decision. We can always bring @Model back later.
    • Removes corner-case usage and difficult to answer questions about configuring @Model as things we need to handle
      • @Model data classes, equals, hashcode, etc.
      • How do I have some properties “observed” and others not?
      • How do I specify structural vs. referential equality to be used in observation?
    • Reduces "magic" in the system. Would reduce the likelihood of someone assuming system was smarter than it is (ie, it knowing how to diff a list)
    • Makes the granularity of observation more intuitive.
    • Improves refactorability from variable -> property on class
    • Potentially opens up possibilities to do hand-crafted State-specific optimizations
    • More closely aligns with the rest of the ecosystem and reduces ambiguity towards immutable or us "embracing mutable state"

    Migration Notes

    Almost all existing usages of @Model are fairly trivially transformed in one of two ways. The example below has a @Model class with two properties just for the sake of example, and has it being used in a composable.

    @Model class Position(
     var x: Int,
     var y: Int
    )
    
    @Composable fun Example() {
     var p = remember { Position(0, 0) }
     PositionChanger(
       position=p,
       onXChange={ p.x = it }
       onYChange={ p.y = it }
     )
    }
    

    Alternative 1: Use State<OriginalClass> and create copies.

    This approach is made easier with Kotlin’s data classes. Essentially, make all previously var properties into val properties of a data class, and then use state instead of remember, and assign the state value to cloned copies of the original using the data class copy(...) convenience method.

    It’s important to note that this approach only works when the only mutations to that class were done in the same scope that the State instance is created. If the class is internally mutating itself outside of the scope of usage, and you are relying on the observation of that, then the next approach is the one you will want to use.

    data class Position(
     val x: Int,
     val y: Int
    )
    
    @Composable fun Example() {
     var p by state { Position(0, 0) }
     PositionChanger(
       position=p,
       onXChange={ p = p.copy(x=it) }
       onYChange={ p = p.copy(y=it) }
     )
    }
    

    Alternative 2: Use mutableStateOf and property delegates

    This approach is made easier with Kotlin’s property delegates and the mutableStateOf API which allows you to create MutableState instances outside of composition. Essentially, replace all var properties of the original class with var properties with mutableStateOf as their property delegate. This has the advantage that the usage of the class will not change at all, only the internal implementation of it. The behavior is not completely identical to the original example though, as each property is now observed/subscribed to individually, so the recompositions you see after this refactor could be more narrow (a good thing).

    class Position(x: Int, y: Int) {
     var x by mutableStateOf(x)
     var y by mutableStateOf(y)
    }
    
    // source of Example is identical to original
    @Composable fun Example() {
     var p = remember { Position(0, 0) }
     PositionChanger(
       position=p,
       onXChange={ p.x = it }
       onYChange={ p.y = it }
     )
    }
    

    (I409e8, b/152050010, b/146362815, b/146342522, b/143413369, b/135715219, b/143263925, b/139653744)

Bug Fixes

  • Removed deprecated DrawBackground API in favor of drawBackground extension APIs on Modifier. Refactored color, brush and paint drawBackground implementations to reduce code paths as well as remove requirement for Modifier to be created as part of composition. (I0343a, b/155999867)

Version 0.1.0-dev11

May 14, 2020

androidx.compose:compose-compiler:0.1.0-dev11 and androidx.compose:compose-runtime:0.1.0-dev11 are released. Version 0.1.0-dev11 contains these commits.

API Changes

  • Added an adapter for Flow. Example of the usage:

    val value by flow.collectAsState()
    

    (If2198, b/153375923)

Bug Fixes

  • Updated higher level compose APIs that expose a Canvas to expose CanvasScope instead. This removes the need for consumers to maintain their own Paint objects. For consumers that still require access to a Canvas they can use the drawCanvas extension method which provides a callback to issue drawing commands with the underlying Canvas. (I80afd)
  • WithConstraints trailing lambda API has been changed. Now instead of two params it has a receiver scope which in addition to constraints and layoutDirection provides minWidth, maxWidth, minHeight, and maxHeight properties in Dp (I91b9a, b/149979702)
  • Added symmetric padding modifier. (I39840)

Version 0.1.0-dev10

April 29, 2020

androidx.compose:compose-compiler:0.1.0-dev10 and androidx.compose:compose-runtime:0.1.0-dev10 are released. Version 0.1.0-dev10 contains these commits.

New Features

  • Rebased on a newer version of the Kotlin compiler's IR backend, which means that many of the features that previously didn't work with the IR backend (like non-composable coroutines!) should now work! This should mean you run into fewer cryptic "Backend Internal error" messages, and don't need to work as hard to separate your code into IR and non-IR modules. However, the IR backend is still experimental and still has some bugs (just far fewer of them) so try things out and enjoy but keep in mind it's still a work in progress.

Version 0.1.0-dev09

April 15, 2020

androidx.compose:compose-compiler:0.1.0-dev09 and androidx.compose:compose-runtime:0.1.0-dev09 are released. Version 0.1.0-dev09 contains these commits.

API Changes

  • [Mutable]State property delegate operators moved to extensions to support Kotlin 1.4 property delegate optimizations. Callers must add imports to continue using by state { ... } or by mutableStateOf(...). (I5312c)

Bug Fixes

  • Updated wrapContentWidth and wrapContentHeight to expect vertical or horizontal Alignment rather than any Alignment. The gravity modifier was updated to accept vertical or horizontal Alignment. Row, Column, and Stack were updated to support custom continuous Alignments. (Ib0728)
  • ui-text module was renamed to ui-text-core (I57dec)
  • Improved DrawModifier API ((Ibaced, b/152919067)):
    • Made the receiver scope for draw() ContentDrawScope
    • Removed all parameters on draw()
    • DrawScope has same interface as former CanvasScope
    • ContentDrawScope has drawContent() method
  • ColoredRect has been deprecated. Use Box(Modifier.preferredSize(width, height).drawBackground(color)) instead. (I499fa, b/152753731)

Version 0.1.0-dev08

April 1, 2020

androidx.compose:compose-compiler:0.1.0-dev08 and androidx.compose:compose-runtime:0.1.0-dev08 are released. Version 0.1.0-dev08 contains these commits.

Bug Fixes

  • Replaced Modifier plus operator with factory extension functions (I225e4)
  • RowScope and ColumnScope members are now accessible outside Row and Column. (I3a641)

Version 0.1.0-dev07

March 18, 2020

androidx.compose:compose-compiler:0.1.0-dev07 and androidx.compose:compose-runtime:0.1.0-dev07 are released. Version 0.1.0-dev07 contains these commits.

API Changes

  • androidx.compose.ViewComposer has been moved to androidx.ui.node.UiComposer. (Idef00)
  • androidx.compose.Emittable has been removed. It was redundant with ComponentNode. (Idef00)
  • `androidx.compose.ViewAdapters has been removed. They are no longer a supported use case. (Idef00)
  • Compose.composeInto has been deprecated. Use setContent or setViewContent instead. (Idef00)
  • Compose.disposeComposition has been deprecated. Use the dispose method on the Composition returned by setContent instead. (Idef00)
  • androidx.compose.Compose.subcomposeInto has moved to androidx.ui.core.subcomposeInto. (Idef00)
  • ComponentNode#emitInsertAt has been renamed to ComponentNode#insertAt. (Idef00)
  • ComponentNode#emitRemoveAt has been renamed to ComponentNode#removeAt. (Idef00)
  • ComponentNode#emitMode has been renamed to ComponentNode#move. (Idef00)

Bug Fixes

  • Renamed LayoutFlexible to LayoutWeight. Renamed tight parameter to fill. (If4738)
  • WithConstraints got LayoutDirection parameter (I6d6f7)

Version 0.1.0-dev06

March 4, 2020

androidx.compose:compose-compiler:0.1.0-dev06 and androidx.compose:compose-runtime:0.1.0-dev06 are released. Version 0.1.0-dev06 contains these commits.

New Features

  • Updated the ComposeFlags.COMPOSER_PARAM flag to be true, which will change the code generation strategy for the compose plugin. At a high level, this causes @Composable functions to be generated with an additional synthetic parameter, which is passed through to subsequent @Composable calls in order for the runtime to properly manage execution. This is a significant binary breaking change, however, should preserve source-level compatibility in all sanctioned usage of compose. (aosp/1226314)

Version 0.1.0-dev05

February 19, 2020

androidx.compose:compose-compiler:0.1.0-dev05 and androidx.compose:compose-runtime:0.1.0-dev05 are released. Version 0.1.0-dev05 contains these commits.

API Changes

  • Breaking changes to the ambients API. See log and Ambient<T> documentation for details (I4c7ee, b/143769776)

Bug Fixes

  • Replaced ButtonStyle with distinct functions and removed text (string) overload. See updated samples for usage information. (If63ab, b/146478620, b/146482131)

Version 0.1.0-dev04

January 29, 2020

androidx.compose:compose-compiler:0.1.0-dev04 and androidx.compose:compose-runtime:0.1.0-dev04 are released. The commits included in this version can be found here.

API Changes

  • Added areEquivalent callback to MutableState (Ic2ef8)
  • Removed Component and refactor top-level composition APIs (I1f22e)
  • Transform composable calls with composer param (I1691e)
  • Remove Composition classes in favor of Composer base class (Ieadbf)
  • Mark State<T> and MutableState<T> as stable types (b/146557624)
  • Add currentComposerIntrinsic and tests to ensure correct param passing (I133f0)
  • Made ModelObserver single-threaded. (Ica33d)
  • Correctly generate groups around inline composable calls (Ibf739)
  • Remove unused EffectsDsl annotation (Ibe81d)
  • Added a @Stable annotation. Marked Modifier as stable. (Iacba7)
  • Introduced MutableState, State, mutableStateOf APIs (I98291)
  • Refactored effects to @Composable (Ie2686)
  • Improved performance of ObserverMap and ModelObserver. (Ieb9b6)
  • Changed read observations to allow observing non-ComponentNodes. (Ia4d93)