Preamble
Jetpack Compose is a modern toolkit for building an Android user interface. Jetpack Compose simplifies and speeds up UI development on Android with less code, powerful tools and intuitive Kotlin API.
In this article, you will build a simple UI component with declaration functions. You will not edit any XML layout or directly initialize UI widgets. Instead, you will call the Jetpack Compose functions to call which elements you want and the Compose compiler will do the rest.
Note: The examples in this article are done on the latest version of Android Studio Preview
Create a Jetpack Compose support application
If you want to start a new project that supports Jetpack Compose by default, Android Studio has included new project templates so you can get started. To create a new project including Jetpack Compose , perform the following steps:
- If you are at the Welcome to Android Studio window, select Start a new Android Studio project . If you are on an open project, choose File> New> New Project from the menu bar.
- In the Select a Project Template window, select Empty Compose Activity and then Next .
- In the Configure your project window, perform the following steps:
- Set the Name, Package name and Save location for the project.
- Note that in the Language menu, Kotlin is the only option because Jetpack Compose only works with classes written in the Kotlin language.
- At the Minimum API level dropdown option, select API level 21 or higher .
- Select Finish
And here is the result of the project you just created: 
Add Jetpack Compose to the current project
If you want to use Jetpack Compose in an existing project, you will need to configure your project with the required settings and dependencies.
Configure the Gradle file
You need to set the minimum API of the application to 21 or higher and enable Jectpack Compose in the app's build.gradle file as shown below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | android <span class="token punctuation">{</span> defaultConfig <span class="token punctuation">{</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> minSdkVersion <span class="token number">21</span> <span class="token punctuation">}</span> buildFeatures <span class="token punctuation">{</span> <span class="token comment">// Enables Jetpack Compose for this module</span> compose <span class="token boolean">true</span> <span class="token punctuation">}</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token comment">// Set both the Java and Kotlin compilers to target Java 8.</span> compileOptions <span class="token punctuation">{</span> sourceCompatibility JavaVersion <span class="token punctuation">.</span> <span class="token constant">VERSION_1_8</span> targetCompatibility JavaVersion <span class="token punctuation">.</span> <span class="token constant">VERSION_1_8</span> <span class="token punctuation">}</span> kotlinOptions <span class="token punctuation">{</span> jvmTarget <span class="token operator">=</span> <span class="token double-quoted-string string">"1.8"</span> <span class="token punctuation">}</span> <span class="token punctuation">}</span> |
Use the Kotlin-Gradle experimental plugin
Jetpack Compose currently requires a trial version of the Kotlin-Gradle plugin. To add this plugin, add the file build.gradle as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | buildscript <span class="token punctuation">{</span> repositories <span class="token punctuation">{</span> <span class="token function">google</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token function">jcenter</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token comment">// To download the required version of the Kotlin-Gradle plugin,</span> <span class="token comment">// add the following repository.</span> maven <span class="token punctuation">{</span> url <span class="token single-quoted-string string">'https://dl.bintray.com/kotlin/kotlin-eap'</span> <span class="token punctuation">}</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> dependencies <span class="token punctuation">{</span> classpath <span class="token single-quoted-string string">'com.android.tools.build:gradle:4.0.0-alpha01'</span> classpath <span class="token single-quoted-string string">'org.jetbrains.kotlin:kotlin-gradle-plugin:1.3.60-eap-25'</span> <span class="token punctuation">}</span> <span class="token punctuation">}</span> allprojects <span class="token punctuation">{</span> repositories <span class="token punctuation">{</span> <span class="token function">google</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token function">jcenter</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> maven <span class="token punctuation">{</span> url <span class="token single-quoted-string string">'https://dl.bintray.com/kotlin/kotlin-eap'</span> <span class="token punctuation">}</span> <span class="token punctuation">}</span> <span class="token punctuation">}</span> |
Add the Jetpack Compose toolkit to dependencies
Add the Jetpack Compose toolkit to the dependencies of the build.gradle file as follows:
1 2 3 4 5 6 7 8 | dependencies <span class="token punctuation">{</span> <span class="token comment">// You also need to include the following Compose toolkit dependencies.</span> implementation <span class="token single-quoted-string string">'androidx.ui:ui-tooling:0.1.0-dev02'</span> implementation <span class="token single-quoted-string string">'androidx.ui:ui-layout:0.1.0-dev02'</span> implementation <span class="token single-quoted-string string">'androidx.ui:ui-material:0.1.0-dev02'</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">}</span> |
Use Live Preview
Live Preview is a feature of ANdorid Studio that allows you to test and compare composible functions via orientation, font size and theme without having to deploy the application again.
As seen in the image above, you can have multiple previews of a composable functions with different font size, zoom, or theme limits. Alternatively, you can click on the elements in the preview to quickly navigate to the function that can be combined for that element in the code editor.
Create a basic Live Preview
Here is an example of a composable function called TutorialPreviewTemplate() :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | @Composable fun <span class="token function">TutorialPreviewTemplate</span> <span class="token punctuation">(</span> colors <span class="token punctuation">:</span> MaterialColors <span class="token operator">=</span> lightThemeColors <span class="token punctuation">,</span> typography <span class="token punctuation">:</span> MaterialTypography <span class="token operator">=</span> themeTypography <span class="token punctuation">)</span> <span class="token punctuation">{</span> val context <span class="token operator">=</span> <span class="token operator">+</span> <span class="token function">ambient</span> <span class="token punctuation">(</span> ContextAmbient <span class="token punctuation">)</span> val previewPosts <span class="token operator">=</span> <span class="token function">getPostsWithImagesLoaded</span> <span class="token punctuation">(</span> posts <span class="token punctuation">.</span> <span class="token function">subList</span> <span class="token punctuation">(</span> <span class="token number">1</span> <span class="token punctuation">,</span> <span class="token number">2</span> <span class="token punctuation">)</span> <span class="token punctuation">,</span> context <span class="token punctuation">.</span> resources <span class="token punctuation">)</span> val post <span class="token operator">=</span> previewPosts <span class="token punctuation">[</span> <span class="token number">0</span> <span class="token punctuation">]</span> <span class="token function">MaterialTheme</span> <span class="token punctuation">(</span> colors <span class="token operator">=</span> colors <span class="token punctuation">,</span> typography <span class="token operator">=</span> typography <span class="token punctuation">)</span> <span class="token punctuation">{</span> Surface <span class="token punctuation">{</span> <span class="token function">PostCardTop</span> <span class="token punctuation">(</span> post <span class="token punctuation">)</span> <span class="token punctuation">}</span> <span class="token punctuation">}</span> <span class="token punctuation">}</span> |
To create a live preview, create a new composable function without parameters including the @Preview annotation above the @Composable annotation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | <span class="token comment">/// This is the original composable function.</span> @Composable fun <span class="token function">TutorialPreviewTemplate</span> <span class="token punctuation">(</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">}</span> <span class="token comment">// A new composable function that applies the @Preview annotation and does not</span> <span class="token comment">// take any parameters.</span> @Preview @Composable fun <span class="token function">TutorialPreview</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token comment">// Call the composable function that you would like to</span> <span class="token comment">// create a live preview for.</span> <span class="token function">TutorialPreviewTemplate</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token punctuation">}</span> |
When you create or modify a live preview, you need to rebuild the project to see the changes. Select Build> Make Project on the menu bar.
You can create multiple live previews, appearing side by side in the IDE Preview window as shown below, which is useful for comparing composable functions in action.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | <span class="token comment">/// This is the original composable function.</span> @Composable fun <span class="token function">TutorialPreviewTemplate</span> <span class="token punctuation">(</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">}</span> @Preview @Composable fun <span class="token function">TutorialPreview</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">.</span> <span class="token punctuation">}</span> <span class="token comment">// This live preview uses the app's dark theme.</span> @Preview @Composable fun <span class="token function">TutorialPreviewDark</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token comment">// Although you can't pass arguments to the live preview function itself,</span> <span class="token comment">// you can pass arguments to the composable function that it calls.</span> <span class="token function">TutorialPreviewTemplate</span> <span class="token punctuation">(</span> colors <span class="token operator">=</span> darkThemeColors <span class="token punctuation">)</span> <span class="token punctuation">}</span> |
Include arguments via @Preview annotation
The @Preview Annotation may contain parameters so you can change the way the IDE defines a composable function on the Preview window. In the example below, you can name the live preview by passing a string of characters, which helps you identify the preview together:
1 2 3 4 5 6 7 8 9 10 11 12 13 | <span class="token comment">// Pass a name for the preview to easily identify it in the Preview window.</span> @ <span class="token function">Preview</span> <span class="token punctuation">(</span> <span class="token double-quoted-string string">"Default colors"</span> <span class="token punctuation">)</span> @Composable fun <span class="token function">TutorialPreview</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token function">TutorialPreviewTemplate</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token punctuation">}</span> @ <span class="token function">Preview</span> <span class="token punctuation">(</span> <span class="token double-quoted-string string">"Dark colors"</span> <span class="token punctuation">)</span> @Composable fun <span class="token function">TutorialPreviewDark</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token function">TutorialPreviewTemplate</span> <span class="token punctuation">(</span> colors <span class="token operator">=</span> darkThemeColors <span class="token punctuation">)</span> <span class="token punctuation">}</span> |
The @Preview parameter you can supplement with the following arguments:
-
widthDp: Maximum width, measured in dp, that the IDE can use when displaying live previews. This is useful when you want to preview your composable function on limited screen sizes. -
heightDp: Maximum height, measured in dp, that the IDE can use when displaying live previews. This is useful when you want to preview your composable function on limited screen sizes. -
fontScale: The ratio ratio, relative to the base destiny ratio (1f) of the font. This is useful when you want to test the composable function for different font size options.
1 2 3 4 5 6 | @ <span class="token function">Preview</span> <span class="token punctuation">(</span> <span class="token double-quoted-string string">"Font scaling 1.5, height 300"</span> <span class="token punctuation">,</span> fontScale <span class="token operator">=</span> <span class="token number">1.5</span> f <span class="token punctuation">,</span> heightDp <span class="token operator">=</span> <span class="token number">300</span> <span class="token punctuation">)</span> @Composable fun <span class="token function">TutorialPreviewFontscale</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token function">TutorialPreviewTemplate</span> <span class="token punctuation">(</span> <span class="token punctuation">)</span> <span class="token punctuation">}</span> |
summary
Jetpack Compose is the future that Android developers need to build UI for their applications more quickly and intuitively. And what do you think about it, please comment and share your feelings to everyone.